cuprum-rails 0.1.0 → 0.2.0

data/lib/cuprum/rails/serializers/json/active_record_serializer.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
+require 'cuprum/rails/serializers/base_serializer'
 require 'cuprum/rails/serializers/json'
-require 'cuprum/rails/serializers/json/serializer'
 
 module Cuprum::Rails::Serializers::Json
   # Converts ActiveRecord record to JSON using the #as_json method.
-  class ActiveRecordSerializer < Cuprum::Rails::Serializers::Json::Serializer
+  class ActiveRecordSerializer < Cuprum::Rails::Serializers::BaseSerializer
     # Converts the ActiveRecord record to JSON.
     #
     # Calls and returns the #as_json method of the record.

data/lib/cuprum/rails/serializers/json/array_serializer.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
+require 'cuprum/rails/serializers/base_serializer'
 require 'cuprum/rails/serializers/json'
-require 'cuprum/rails/serializers/json/serializer'
 
 module Cuprum::Rails::Serializers::Json
   # Converts Array data structures to JSON based on configured serializers.
-  class ArraySerializer < Cuprum::Rails::Serializers::Json::Serializer
+  class ArraySerializer < Cuprum::Rails::Serializers::BaseSerializer
     # Converts the array to JSON using the given serializers.
     #
     # First, #call finds the best serializer from the :serializers Hash for each
@@ -15,26 +15,27 @@ module Cuprum::Rails::Serializers::Json
     # combined into a new Array and returned.
     #
     # @param array [Array] The array to convert to JSON.
-    # @param serializers [Hash<Class, #call>] The serializers for different
-    #   object types.
+    # @param context [Cuprum::Rails::Serializers::Context] The serialization
+    #   context, which includes the configured serializers for attributes or
+    #   collection items.
     #
     # @return [Array] a JSON-compatible representation of the array.
     #
     # @raise UndefinedSerializerError if there is no matching serializer for
     #   any of the items in the array.
-    def call(array, serializers:)
+    def call(array, context:)
       raise ArgumentError, 'object must be an Array' unless array.is_a?(Array)
 
-      array.map { |item| super(item, serializers: serializers) }
+      array.map { |item| super(item, context: context) }
     end
 
     private
 
-    def handle_recursion!(_object)
+    def allow_recursion?
       # Call serializes the items, not the array. Because the context changes,
       # we don't need to check for recursion (unless the Array contains itself,
       # in which case here there be dragons).
-      yield
+      true
     end
   end
 end

data/lib/cuprum/rails/serializers/json/attributes_serializer.rb

@@ -1,217 +1,140 @@
 # frozen_string_literal: true
 
+require 'cuprum/rails/serializers/base_serializer'
 require 'cuprum/rails/serializers/json'
-require 'cuprum/rails/serializers/json/serializer'
 
 module Cuprum::Rails::Serializers::Json
-  # Converts the object to JSON by serializing the specified attributes.
+  # Generates a JSON representation of the object's attributes.
   #
-  # When called, the serializer will convert each of the given attributes to
-  # JSON using the given serializers.
+  # Defined properties are inherited from the parent serializer. This allows
+  # you to extend existing serializers with additional functionality.
   #
-  # Defined attributes are inherited from the parent serializer. This allows you
-  # to extend existing serializers with additional functionality.
-  #
-  # @example Defining A Base Serializer
-  #   class RecordSerializer < Cuprum::Rails::Serializers::Json::AttributesSerializer # rubocop:disable Layout/LineLength
-  #     attribute :id
+  # @example Serializing an attribute.
+  #   User = Struct.new(:first_name, :last_name, :salary, :department)
+  #   class FirstNameSerializer < Cuprum::Rails::Serializers::Json::AttributesSerializer
+  #     attribute :first_name
   #   end
   #
-  #   book        = Book.new(
-  #     id:           10,
-  #     title:        'Gideon the Ninth',
-  #     author:       'Tamsyn Muir',
-  #     published_at: '2019-09-10'
-  #   )
-  #   serializers = Cuprum::Rails::Serializers::Json.default_serializers
+  #   user       = User.new('Alan', 'Bradley')
+  #   serializer = FirstNameSerializer.new
+  #   serializer.call(user, context: context)
+  #   #=> {
+  #     'first_name' => 'Alan'
+  #   }
   #
-  #   RecordSerializer.new.call(book, serializers: serializers)
-  #   #=> { id: 10 }
+  # @example Using a custom serializer.
+  #   User = Struct.new(:first_name, :last_name, :salary, :department)
+  #   class SalarySerializer < Cuprum::Rails::Serializers::Json::AttributesSerializer
+  #     attribute :salary, serializer: BigDecimalSerializer
+  #   end
+  #
+  #   user       = User.new('Alan', 'Bradley', BigDecimal('100000'))
+  #   serializer = SalarySerializer.new
+  #   serializer.call(user, context: context)
+  #   #=> {
+  #     'salary' => '0.1e6'
+  #   }
   #
-  # @example Defining A Record Serializer
-  #   class BookSerializer < RecordSerializer
-  #     attribute :title, Cuprum::Rails::Serializers::Json::IdentitySerializer.instance # rubocop:disable Layout/LineLength
-  #     attribute :author do |author|
-  #       "by: #{author}"
-  #     end
+  # @example Using a custom mapping.
+  #   User = Struct.new(:first_name, :last_name, :hire_date)
+  #   class HireDateSerializer < Cuprum::Rails::Serializers::Json::AttributesSerializer
+  #     attribute(:hire_date) { |value| value&.iso8601 }
   #   end
   #
-  #   BookSerializer.new.call(book, serializers: serializers)
+  #   user       = User.new('Alan', 'Bradley', Date.new(1977, 5, 25))
+  #   serializer = HireDateSerializer.new
+  #   serializer.call(user, context: context)
   #   #=> {
-  #         id:     10,
-  #         title:  'Gideon the Ninth',
-  #         author: 'by: Tamsyn Muir'
-  #       }
+  #     'hire_date' => '1977-05-25'
+  #   }
   #
-  # @example Defining a Serializer Subclass
-  #   class PublishedBookSerializer < BookSerializer
-  #     attribute :published_at
+  # @example Serializing multiple attributes.
+  #   User = Struct.new(:first_name, :last_name, :hire_date)
+  #   class UserSerializer < Cuprum::Rails::Serializers::Json::AttributesSerializer
+  #     attributes \
+  #       :first_name,
+  #       :last_name,
+  #       hire_date: :iso8601
   #   end
   #
-  #   PublishedBookSerializer.new.call(book, serializers: serializers)
+  #   user       = User.new('Alan', 'Bradley', Date.new(1977, 5, 25))
+  #   serializer = HireDateSerializer.new
+  #   serializer.call(user, context: context)
   #   #=> {
-  #         id:           10,
-  #         title:        'Gideon the Ninth',
-  #         author:       'by: Tamsyn Muir',
-  #         published_at: '2019-09-10'
-  #       }
-  class AttributesSerializer < Cuprum::Rails::Serializers::Json::Serializer
-    # Error class used when a serializer calls itself.
-    class AbstractSerializerError < StandardError; end
+  #     'first_name' => 'Alan',
+  #     'last_name'  => 'Bradley',
+  #     'hire_date'  => '1977-05-25'
+  #   }
+  #
+  # @see Cuprum::Rails::Serializers::Json::PropertiesSerializer
+  class AttributesSerializer < Cuprum::Rails::Serializers::Json::PropertiesSerializer # rubocop:disable Layout/LineLength
+    @abstract_class = true
 
     class << self
       # Registers the attribute to be serialized.
       #
-      # This class method will raise an AbstractSerializerError if called on
-      # AttributesSerializer directly. Instead, create a subclass and define
-      # attributes on that subclass.
-      #
-      # @return [Class] the serializer class.
-      #
-      # @raise [AbstractSerializerError] if called on AttributesSerializer.
-      #
-      # @see AttributesSerializer#call.
-      #
-      # @overload attribute(attr_name)
-      #   Registers the attribute for serialization. When the serializer is
-      #   called, the value of the attribute will be converted to JSON using the
-      #   serializers passed to #call.
+      # @param name [String, Symbol] the name of the attribute to serialize.
+      #   This will determine the hash key of the serialized value, as well as
+      #   the base value to be serialized.
+      # @param serializer [#call] the serializer used to serialize the value. If
+      #   no serializer is given, the default serializer (if any) will be used.
       #
-      #   @param attr_name [String, Symbol] The name of the attribute to
-      #     serialize.
+      # @yield If a block is given, the block is used to transform the attribute
+      #   value prior to serialization.
+      # @yieldparam value [Object] the attribute value.
+      # @yieldreturn [Object] the transformed value.
       #
-      # @overload attribute(attr_name, serializer)
-      #   Registers the attribute for serialization. When the serializer is
-      #   called, the given serializer will be called with the value of the
-      #   attribute and the configured serializers.
-      #
-      #   @param attr_name [String, Symbol] The name of the attribute to
-      #     serialize.
-      #   @param serializer [Cuprum::Rails::Serializers::Json::Serializer] the
-      #     serializer to use when converting the attribute to JSON.
-      #
-      # @overload attribute(attr_name, &block)
-      #   Registers the attribute for serialization. When the serializer is
-      #   called, the block will be called with the value of the attribute and
-      #   the configured serializers.
-      #
-      #   @param attr_name [String, Symbol] The name of the attribute to
-      #     serialize.
+      # @raise AbstractSerializerError when attempting to define a serialized
+      #   property on an abstract class.
+      def attribute(name, serializer: nil, &block)
+        property(
+          name,
+          scope:      name,
+          serializer: serializer,
+          &block
+        )
+      end
+
+      # Registers the attributes to be serialized.
       #
-      #   @yield The value of the attribute and the configured serializers.
+      # @param attribute_names [Array<String, Symbol>] the names of the
+      #   attributes to serialize.
+      # @param attribute_mappings [Hash{String, Symbol => #to_proc}] the names
+      #   and mappings of additional attributes to serialize.
       #
-      #   @yieldreturn the attribute value converted to JSON.
-      def attribute(attr_name, serializer = nil, &block)
-        validate_subclass!
-        validate_attribute_name!(attr_name)
-        validate_serializer!(serializer)
+      # @raise AbstractSerializerError when attempting to define a serialized
+      #   property on an abstract class.
+      def attributes(*attribute_names, **attribute_mappings)
+        require_concrete_class!
 
-        own_attributes[attr_name.to_s] = serializer || block
+        validate_property_names!(*attribute_names, *attribute_mappings.keys)
+        validate_property_mappings!(*attribute_mappings.values)
 
-        self
-      end
+        attribute_names.each { |name| attribute(name) }
 
-      # @return [Hash<String, Object>] the defined attributes and respective
-      #   serializers.
-      def attributes(*_, **_)
-        all_attributes
-      end
-
-      protected
-
-      def own_attributes
-        @own_attributes ||= {}
+        attribute_mappings.each { |name, mapping| attribute(name, &mapping) }
       end
 
       private
 
-      def all_attributes
-        ancestors
-          .select do |ancestor|
-            ancestor < Cuprum::Rails::Serializers::Json::AttributesSerializer
-          end # rubocop:disable Style/MultilineBlockChain
-          .reverse_each
-          .reduce({}) { |hsh, ancestor| hsh.merge(ancestor.own_attributes) }
-      end
-
-      def validate_attribute_name!(attr_name)
-        raise ArgumentError, "attribute name can't be blank" if attr_name.nil?
-
-        unless attr_name.is_a?(String) || attr_name.is_a?(Symbol)
-          raise ArgumentError, 'attribute name must be a string or symbol'
-        end
-
-        return unless attr_name.empty?
-
-        raise ArgumentError, "attribute name can't be blank"
-      end
-
-      def validate_serializer!(serializer)
-        return if serializer.nil? || serializer.respond_to?(:call)
+      def validate_property_mappings!(*mappings)
+        mappings.each do |mapping|
+          next if mapping.respond_to?(:to_proc)
 
-        raise ArgumentError, 'serializer must respond to #call'
-      end
-
-      def validate_subclass!
-        unless self == Cuprum::Rails::Serializers::Json::AttributesSerializer
-          return
+          raise ArgumentError, 'property mapping must respond to #to_proc'
         end
-
-        raise AbstractSerializerError,
-          'AttributesSerializer is an abstract class - create a subclass to' \
-          ' define attributes'
       end
-    end
 
-    # Converts the defined attributes to JSON.
-    #
-    # @param object [Object] The object to convert to JSON.
-    # @param serializers [Hash<Class, #call>] The serializers for different
-    #   object types.
-    #
-    # @return [Hash<String, Object] a JSON-compatible representation of the
-    #   object's attributes.
-    def call(object, serializers:)
-      self.class.attributes.each.with_object({}) \
-      do |(attr_name, serializer), hsh|
-        attr_value     = object.send(attr_name)
-        hsh[attr_name] =
-          serialize_attribute(
-            attr_value:  attr_value,
-            serializer:  serializer,
-            serializers: serializers
-          ) { super(attr_value, serializers: serializers) }
+      def validate_property_names!(*names)
+        names.each { |name| validate_property_name!(name) }
       end
     end
 
     private
 
-    def apply_block(attr_value, block:, serializers:)
-      args   = block_argument?(block) ? [attr_value] : []
-      kwargs = block_keyword?(block)  ? { serializers: serializers } : {}
-
-      kwargs.empty? ? block.call(*args) : block.call(*args, **kwargs)
-    end
-
-    def block_argument?(block)
-      block.parameters.any? { |type, _| type == :req || type == :rest } # rubocop:disable Style/MultipleComparison
-    end
-
-    def block_keyword?(block)
-      block.parameters.any? do |type, name|
-        (type == :keyreq && name == :serializers) || type == :keyrest
-      end
-    end
-
-    def serialize_attribute(attr_value:, serializer:, serializers:)
-      case serializer
-      when Cuprum::Rails::Serializers::Json::Serializer
-        serializer.call(attr_value)
-      when Proc
-        apply_block(attr_value, block: serializer, serializers: serializers)
-      else
-        yield
-      end
+    def allow_recursion?
+      # Call serializes the attributes, not the object itself.
+      true
     end
   end
 end

data/lib/cuprum/rails/serializers/json/error_serializer.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
+require 'cuprum/rails/serializers/base_serializer'
 require 'cuprum/rails/serializers/json'
-require 'cuprum/rails/serializers/json/serializer'
 
 module Cuprum::Rails::Serializers::Json
   # Converts a Cuprum::Error to JSON using the #as_json method.
-  class ErrorSerializer < Cuprum::Rails::Serializers::Json::Serializer
+  class ErrorSerializer < Cuprum::Rails::Serializers::BaseSerializer
     # Converts the Cuprum error to JSON.
     #
     # Calls and returns the #as_json method of the error.

data/lib/cuprum/rails/serializers/json/hash_serializer.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
+require 'cuprum/rails/serializers/base_serializer'
 require 'cuprum/rails/serializers/json'
-require 'cuprum/rails/serializers/json/serializer'
 
 module Cuprum::Rails::Serializers::Json
   # Converts Hash data structures to JSON based on configured serializers.
-  class HashSerializer < Cuprum::Rails::Serializers::Json::Serializer
+  class HashSerializer < Cuprum::Rails::Serializers::BaseSerializer
     # Converts the hash to JSON using the given serializers.
     #
     # First, #call finds the best serializer from the :serializers Hash for each
@@ -15,30 +15,31 @@ module Cuprum::Rails::Serializers::Json
     # are combined into a new Hash and returned.
     #
     # @param hash [Hash<String, Object>] The hash to convert to JSON.
-    # @param serializers [Hash<Class, #call>] The serializers for different
-    #   object types.
+    # @param context [Cuprum::Rails::Serializers::Context] The serialization
+    #   context, which includes the configured serializers for attributes or
+    #   collection items.
     #
     # @return [Hash] a JSON-compatible representation of the hash.
     #
     # @raise UndefinedSerializerError if there is no matching serializer for
     #   any of the values in the hash.
-    def call(hash, serializers:)
+    def call(hash, context:)
       unless hash.is_a?(Hash) && hash.keys.all? { |key| key.is_a?(String) }
         raise ArgumentError, 'object must be a Hash with String keys'
       end
 
       hash.each.with_object({}) do |(key, value), mapped|
-        mapped[key] = super(value, serializers: serializers)
+        mapped[key] = super(value, context: context)
       end
     end
 
     private
 
-    def handle_recursion!(_object)
+    def allow_recursion?
       # Call serializes the values, not the hash. Because the context changes,
       # we don't need to check for recursion (unless the Hash contains itself,
       # in which case here there be dragons).
-      yield
+      true
     end
   end
 end

data/lib/cuprum/rails/serializers/json/identity_serializer.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
+require 'cuprum/rails/serializers/base_serializer'
 require 'cuprum/rails/serializers/json'
-require 'cuprum/rails/serializers/json/serializer'
 
 module Cuprum::Rails::Serializers::Json
   # Serializer that returns a value object as itself.
-  class IdentitySerializer < Cuprum::Rails::Serializers::Json::Serializer
+  class IdentitySerializer < Cuprum::Rails::Serializers::BaseSerializer
     # Returns the object.
     #
     # This serializer should only be used with value objects: nil, true, false,
@@ -13,7 +13,7 @@ module Cuprum::Rails::Serializers::Json
     #
     # @param object [Object] The object to convert to JSON.
     #
-    # @return [Object] a JSON-compatible Hash representation of the object.
+    # @return [Object] a JSON representation of the object.
     def call(object, **_)
       object
     end