cuprum-rails 0.1.0

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

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+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.
+  #
+  # When called, the serializer will convert each of the given attributes to
+  # JSON using the given serializers.
+  #
+  # 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
+  #   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
+  #
+  #   RecordSerializer.new.call(book, serializers: serializers)
+  #   #=> { id: 10 }
+  #
+  # @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
+  #   end
+  #
+  #   BookSerializer.new.call(book, serializers: serializers)
+  #   #=> {
+  #         id:     10,
+  #         title:  'Gideon the Ninth',
+  #         author: 'by: Tamsyn Muir'
+  #       }
+  #
+  # @example Defining a Serializer Subclass
+  #   class PublishedBookSerializer < BookSerializer
+  #     attribute :published_at
+  #   end
+  #
+  #   PublishedBookSerializer.new.call(book, serializers: serializers)
+  #   #=> {
+  #         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
+
+    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 attr_name [String, Symbol] The name of the attribute to
+      #     serialize.
+      #
+      # @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.
+      #
+      #   @yield The value of the attribute and the configured serializers.
+      #
+      #   @yieldreturn the attribute value converted to JSON.
+      def attribute(attr_name, serializer = nil, &block)
+        validate_subclass!
+        validate_attribute_name!(attr_name)
+        validate_serializer!(serializer)
+
+        own_attributes[attr_name.to_s] = serializer || block
+
+        self
+      end
+
+      # @return [Hash<String, Object>] the defined attributes and respective
+      #   serializers.
+      def attributes(*_, **_)
+        all_attributes
+      end
+
+      protected
+
+      def own_attributes
+        @own_attributes ||= {}
+      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)
+
+        raise ArgumentError, 'serializer must respond to #call'
+      end
+
+      def validate_subclass!
+        unless self == Cuprum::Rails::Serializers::Json::AttributesSerializer
+          return
+        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) }
+      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
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+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
+    # Converts the Cuprum error to JSON.
+    #
+    # Calls and returns the #as_json method of the error.
+    #
+    # @param error [Cuprum::Error] The error to convert to JSON.
+    #
+    # @return [Hash] a JSON-compatible representation of the error.
+    def call(error, **_)
+      unless error.is_a?(Cuprum::Error)
+        raise ArgumentError, 'object must be a Cuprum::Error'
+      end
+
+      error.as_json
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+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
+    # Converts the hash to JSON using the given serializers.
+    #
+    # First, #call finds the best serializer from the :serializers Hash for each
+    # value in the Hash. This is done by walking up the object class's ancestors
+    # to find the closest ancestor which is a key in the :serializers Hash.
+    # The corresponding value is then called with the object, and the results
+    # 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.
+    #
+    # @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:)
+      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)
+      end
+    end
+
+    private
+
+    def handle_recursion!(_object)
+      # 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
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+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
+    # Returns the object.
+    #
+    # This serializer should only be used with value objects: nil, true, false,
+    # Integers, Floats, and Strings.
+    #
+    # @param object [Object] The object to convert to JSON.
+    #
+    # @return [Object] a JSON-compatible Hash representation of the object.
+    def call(object, **_)
+      object
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/serializers/json'
+
+module Cuprum::Rails::Serializers::Json
+  # Converts objects or data structures to JSON based on configured serializers.
+  class Serializer
+    # Error class used when a serializer calls itself.
+    class RecursiveSerializerError < StandardError; end
+
+    # Error class used when there is no matching serializer for the object.
+    class UndefinedSerializerError < StandardError; end
+
+    # @return [Cuprum::Rails::Serializers::Json::Serializer] a cached instance
+    #   of the serializer.
+    def self.instance
+      @instance ||= new
+    end
+
+    # Converts the object to JSON using the given serializers.
+    #
+    # First, #call finds the best serializer from the :serializers Hash. This is
+    # done by walking up the object class's ancestors to find the closest
+    # ancestor which is a key in the :serializers Hash. The corresponding value
+    # is then called with the object.
+    #
+    # @param object [Object] The object to convert to JSON.
+    # @param serializers [Hash<Class, #call>] The serializers for different
+    #   object types.
+    #
+    # @return [Object] a JSON-compatible representation of the object.
+    #
+    # @raise RecursiveSerializerError if the serializer would create an infinite
+    #   loop, e.g. by calling itself.
+    # @raise UndefinedSerializerError if there is no matching serializer for
+    #   the object.
+    def call(object, serializers:)
+      serializer = handle_recursion!(object) do
+        serializer_for(object: object, serializers: serializers)
+      end
+
+      serializer.call(object, serializers: serializers)
+    end
+
+    private
+
+    def handle_recursion!(object)
+      serializer = yield
+
+      return serializer unless instance_of?(serializer.class)
+
+      raise RecursiveSerializerError,
+        "invalid serializer for #{object.class.name} - recursive calls to" \
+        " #{self.class.name}#call"
+    end
+
+    def serializer_for(object:, serializers:)
+      object.class.ancestors.each do |ancestor|
+        return serializers[ancestor] if serializers.key?(ancestor)
+      end
+
+      raise UndefinedSerializerError,
+        "no serializer defined for #{object.class.name}"
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails/serializers'
+
+module Cuprum::Rails::Serializers
+  # Namespace for JSON serializers, which convert objects to a JSON format.
+  module Json
+    autoload :ActiveRecordSerializer,
+      'cuprum/rails/serializers/json/active_record_serializer'
+    autoload :ArraySerializer,
+      'cuprum/rails/serializers/json/array_serializer'
+    autoload :AttributesSerializer,
+      'cuprum/rails/serializers/json/attributes_serializer'
+    autoload :ErrorSerializer,
+      'cuprum/rails/serializers/json/error_serializer'
+    autoload :HashSerializer,
+      'cuprum/rails/serializers/json/hash_serializer'
+    autoload :IdentitySerializer,
+      'cuprum/rails/serializers/json/identity_serializer'
+    autoload :Serializer, 'cuprum/rails/serializers/json/serializer'
+
+    # Default serializers for handling value objects and data structures.
+    #
+    # @return [Hash<Class, Cuprum::Rails::Serializers::Json::Serializer>] the
+    #   default serializers.
+    def self.default_serializers # rubocop:disable Metrics/MethodLength
+      @default_serializers ||= {
+        Array         => self::ArraySerializer.instance,
+        Cuprum::Error => self::ErrorSerializer.instance,
+        Hash          => self::HashSerializer.instance,
+        FalseClass    => self::IdentitySerializer.instance,
+        Float         => self::IdentitySerializer.instance,
+        Integer       => self::IdentitySerializer.instance,
+        NilClass      => self::IdentitySerializer.instance,
+        String        => self::IdentitySerializer.instance,
+        TrueClass     => self::IdentitySerializer.instance
+      }
+    end
+  end
+end

data/lib/cuprum/rails/serializers.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Namespace for serializers, which convert objects to a serialized format.
+  module Serializers
+    autoload :Json, 'cuprum/rails/serializers/json'
+  end
+end

data/lib/cuprum/rails/version.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Cuprum
+  module Rails
+    # @api private
+    #
+    # The current version of the gem.
+    #
+    # @see http://semver.org/
+    module Version
+      # Major version.
+      MAJOR = 0
+      # Minor version.
+      MINOR = 1
+      # Patch version.
+      PATCH = 0
+      # Prerelease version.
+      PRERELEASE = nil
+      # Build metadata.
+      BUILD = nil
+
+      class << self
+        # Generates the gem version string from the Version constants.
+        #
+        # Inlined here because dependencies may not be loaded when processing a
+        # gemspec, which results in the user being unable to install the gem for
+        # the first time.
+        #
+        # @see SleepingKingStudios::Tools::SemanticVersion#to_gem_version
+        def to_gem_version
+          str = +"#{MAJOR}.#{MINOR}.#{PATCH}"
+
+          prerelease = value_of(:PRERELEASE)
+          str << ".#{prerelease}" if prerelease
+
+          build = value_of(:BUILD)
+          str << ".#{build}" if build
+
+          str
+        end
+
+        private
+
+        def value_of(constant)
+          return nil unless const_defined?(constant)
+
+          value = const_get(constant)
+
+          return nil if value.respond_to?(:empty?) && value.empty?
+
+          value
+        end
+      end
+    end
+
+    # @return [String] the current version of the gem.
+    VERSION = Version.to_gem_version
+  end
+end

data/lib/cuprum/rails.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+
+# A Ruby implementation of the command pattern.
+module Cuprum
+  # An integration between Rails and the Cuprum library.
+  module Rails
+    # @return [String] The current version of the gem.
+    def self.version
+      VERSION
+    end
+
+    autoload :Action,           'cuprum/rails/action'
+    autoload :Actions,          'cuprum/rails/actions'
+    autoload :Collection,       'cuprum/rails/collection'
+    autoload :Command,          'cuprum/rails/command'
+    autoload :Commands,         'cuprum/rails/commands'
+    autoload :Controller,       'cuprum/rails/controller'
+    autoload :ControllerAction, 'cuprum/rails/controller_action'
+    autoload :Controllers,      'cuprum/rails/controllers'
+    autoload :Query,            'cuprum/rails/query'
+    autoload :Request,          'cuprum/rails/request'
+    autoload :Responders,       'cuprum/rails/responders'
+    autoload :Responses,        'cuprum/rails/responses'
+    autoload :Resource,         'cuprum/rails/resource'
+    autoload :Routes,           'cuprum/rails/routes'
+    autoload :Routing,          'cuprum/rails/routing'
+    autoload :Serializers,      'cuprum/rails/serializers'
+  end
+end