ama-entity-mapper 0.1.0.beta.2

data/lib/ama-entity-mapper/path/segment.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module AMA
+  module Entity
+    class Mapper
+      class Path
+        # Well, that's quite self-explanatory. Path consists of segments, and
+        # here's one.
+        class Segment
+          attr_reader :name
+          attr_reader :prefix
+          attr_reader :suffix
+
+          def initialize(name, prefix = nil, suffix = nil)
+            @name = name
+            @prefix = prefix
+            @suffix = suffix
+          end
+
+          def to_s
+            "#{@prefix}#{@name}#{@suffix}"
+          end
+
+          def hash
+            @name.hash ^ @prefix.hash ^ @suffix.hash
+          end
+
+          def eql?(other)
+            return false unless other.is_a?(self.class)
+            @name == other.name && @prefix == other.prefix &&
+              @suffix == other.suffix
+          end
+
+          def ==(other)
+            eql?(other)
+          end
+
+          class << self
+            def attribute(name)
+              new(name, '.')
+            end
+
+            def index(name)
+              new(name, '[', ']')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ama-entity-mapper/type.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/ClassLength
+
+require_relative 'mixin/errors'
+require_relative 'mixin/reflection'
+require_relative 'mixin/handler_support'
+require_relative 'context'
+require_relative 'type/parameter'
+require_relative 'type/attribute'
+require_relative 'handler/entity/normalizer'
+require_relative 'handler/entity/denormalizer'
+require_relative 'handler/entity/enumerator'
+require_relative 'handler/entity/injector'
+require_relative 'handler/entity/factory'
+require_relative 'handler/entity/validator'
+
+module AMA
+  module Entity
+    class Mapper
+      # Type wrapper
+      class Type
+        include Mixin::Errors
+        include Mixin::Reflection
+        include Mixin::HandlerSupport
+
+        # @!attribute type
+        #   @return [Class]
+        attr_accessor :type
+        # @!attribute parameters
+        #   @return [Hash{Symbol, AMA::Entity::Mapper::Type::Parameter}]
+        attr_accessor :parameters
+        # @!attribute attributes
+        #   @return [Hash{Symbol, AMA::Entity::Mapper::Type::Attribute}]
+        attr_accessor :attributes
+        # @!attribute virtual
+        #   @return [TrueClass, FalseClass]
+        attr_accessor :virtual
+
+        handler_namespace Handler::Entity
+
+        # @!attribute factory
+        #   @return [AMA::Entity::Mapper::Handler::Entity::Factory]
+        handler :factory, :create
+        # @!attribute normalizer
+        #   @return [AMA::Entity::Mapper::Handler::Entity::Normalizer]
+        handler :normalizer, :normalize
+        # @!attribute denormalizer
+        #   @return [AMA::Entity::Mapper::Handler::Entity::Denormalizer]
+        handler :denormalizer, :denormalize
+        # @!attribute enumerator
+        #   @return [AMA::Entity::Mapper::Handler::Entity::Enumerator]
+        handler :enumerator, :enumerate
+        # @!attribute injector
+        #   @return [AMA::Entity::Mapper::Handler::Entity::Injector]
+        handler :injector, :inject
+        # @!attribute injector
+        #   @return [AMA::Entity::Mapper::Handler::Entity::Validator]
+        handler :validator, :validate
+
+        # @param [Class, Module] klass
+        def initialize(klass, virtual: false)
+          @type = validate_type!(klass)
+          @parameters = {}
+          @attributes = {}
+          @virtual = virtual
+        end
+
+        # Tells if provided object is an instance of this type.
+        #
+        # This doesn't mean all of it's attributes do match requested types.
+        #
+        # @param [Object] object
+        # @return [TrueClass, FalseClass]
+        def instance?(object)
+          object.is_a?(@type)
+        end
+
+        def instance!(object, context)
+          return if instance?(object)
+          message = "Provided object #{object} is not an instance of #{self}"
+          validation_error(message, context: context)
+        end
+
+        # @return [TrueClass, FalseClass]
+        def resolved?
+          attributes.values.all?(&:resolved?)
+        end
+
+        # Validates that type is fully resolved, otherwise raises an error
+        # @param [AMA::Entity::Mapper::Context] context
+        def resolved!(context = Context.new)
+          attributes.values.each { |attribute| attribute.resolved!(context) }
+        end
+
+        # Shortcut for attribute creation.
+        #
+        # @param [String, Symbol] name
+        # @param [Array<AMA::Entity::Mapper::Type>] types
+        # @param [Hash] options
+        def attribute!(name, *types, **options)
+          name = name.to_sym
+          types = types.map do |type|
+            next type if type.is_a?(Parameter)
+            next parameter!(type) if type.is_a?(Symbol)
+            next self.class.new(type) unless type.is_a?(Type)
+            type
+          end
+          attributes[name] = Attribute.new(self, name, *types, **options)
+        end
+
+        # Creates new type parameter
+        #
+        # @param [Symbol] id
+        # @return [Parameter]
+        def parameter!(id)
+          id = id.to_sym
+          return @parameters[id] if @parameters.key?(id)
+          @parameters[id] = Parameter.new(self, id)
+        end
+
+        # Resolves single parameter type. Substitution may be either another
+        # parameter or array of types.
+        #
+        # @param [Parameter] parameter
+        # @param [Parameter, Array<Type>] substitution
+        def resolve_parameter(parameter, substitution)
+          parameter = validate_parameter!(parameter)
+          substitution = validate_substitution!(substitution)
+          clone.tap do |clone|
+            intermediate = attributes.map do |key, value|
+              [key, value.resolve_parameter(parameter, substitution)]
+            end
+            clone.attributes = Hash[intermediate]
+            intermediate = clone.parameters.map do |key, value|
+              [key, value == parameter ? substitution : value]
+            end
+            clone.parameters = Hash[intermediate]
+          end
+        end
+
+        # rubocop:disable Metrics/LineLength
+
+        # @param [Hash<AMA::Entity::Mapper::Type, AMA::Entity::Mapper::Type>] parameters
+        # @return [AMA::Entity::Mapper::Type]
+        def resolve(parameters)
+          parameters.reduce(self) do |carrier, tuple|
+            carrier.resolve_parameter(*tuple)
+          end
+        end
+
+        # rubocop:enable Metrics/LineLength
+
+        def violations(object, context)
+          validator.validate(object, self, context)
+        end
+
+        def valid?(object, context)
+          violations(object, context).empty?
+        end
+
+        def valid!(object, context)
+          violations = self.violations(object, context)
+          return if violations.empty?
+          message = "#{object} has failed type #{to_def} validation: " \
+            "#{violations.join(', ')}"
+          validation_error(message, context: context)
+        end
+
+        def hash
+          @type.hash ^ @attributes.hash
+        end
+
+        def eql?(other)
+          return false unless other.is_a?(self.class)
+          @type == other.type && @attributes == other.attributes
+        end
+
+        def ==(other)
+          eql?(other)
+        end
+
+        def to_s
+          message = "Type #{@type}"
+          unless @parameters.empty?
+            message += " (parameters: #{@parameters.keys})"
+          end
+          message
+        end
+
+        def to_def
+          return @type.to_s if parameters.empty?
+          params = parameters.map do |key, value|
+            value = [value] unless value.is_a?(Enumerable)
+            value = value.map(&:to_def)
+            value = value.size > 1 ? "[#{value.join(', ')}]" : value.first
+            "#{key}:#{value}"
+          end
+          "#{@type}<#{params.join(', ')}>"
+        end
+
+        private
+
+        def validate_type!(type)
+          return type if type.is_a?(Class) || type.is_a?(Module)
+          message = 'Expected Type to be instantiated with ' \
+              "Class/Module instance, got #{type}"
+          compliance_error(message)
+        end
+
+        def validate_parameter!(parameter)
+          return parameter if parameter.is_a?(Parameter)
+          message = "Non-parameter type #{parameter} " \
+              'supplied for resolution'
+          compliance_error(message)
+        end
+
+        def validate_substitution!(substitution)
+          return substitution if substitution.is_a?(Parameter)
+          substitution = [substitution] if substitution.is_a?(self.class)
+          if substitution.is_a?(Enumerable)
+            return validate_substitutions!(substitution)
+          end
+          message = 'Provided substitution is neither another Parameter ' \
+              'or Array of Types: ' \
+              "#{substitution} (#{substitution.class})"
+          compliance_error(message)
+        end
+
+        def validate_substitutions!(substitutions)
+          if substitutions.empty?
+            compliance_error('Empty list of substitutions passed')
+          end
+          invalid = substitutions.reject do |substitution|
+            substitution.is_a?(Type)
+          end
+          return substitutions if invalid.empty?
+          compliance_error("Invalid substitutions supplied: #{invalid}")
+        end
+      end
+    end
+  end
+end

data/lib/ama-entity-mapper/type/analyzer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative '../type'
+require_relative 'any'
+
+module AMA
+  module Entity
+    class Mapper
+      class Type
+        # Some naive automatic attribute discovery
+        class Analyzer
+          # @param [Class, Module] klass
+          # @return [AMA::Entity::Mapper:Type]
+          def self.analyze(klass)
+            type = Type.new(klass)
+            writers = klass.instance_methods.grep(/\w+=$/)
+            writers.map do |writer|
+              attribute = writer[0..-2]
+              type.attribute!(attribute, Type::Any::INSTANCE, nullable: true)
+            end
+            type
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ama-entity-mapper/type/any.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative '../type'
+require_relative '../mixin/errors'
+
+module AMA
+  module Entity
+    class Mapper
+      class Type
+        # Used as a wildcard to pass anything through
+        class Any < Type
+          include Mixin::Errors
+
+          def initialize
+            super(self.class)
+            denormalizer_block { |entity, *| entity }
+            normalizer_block { |entity, *| entity }
+            validator_block { |*| [] }
+          end
+
+          INSTANCE = new
+
+          def parameters
+            {}
+          end
+
+          def attributes
+            {}
+          end
+
+          def parameter!(*)
+            compliance_error('Tried to declare parameter on Any type')
+          end
+
+          def resolve_parameter(*)
+            self
+          end
+
+          def instance?(object, *)
+            !object.nil?
+          end
+
+          def hash
+            self.class.hash
+          end
+
+          def eql?(other)
+            other.is_a?(Type)
+          end
+
+          def ==(other)
+            eql?(other)
+          end
+
+          def to_s
+            'Any Type'
+          end
+
+          def to_def
+            '*'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ama-entity-mapper/type/attribute.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/ClassLength
+
+require_relative '../handler/attribute/validator'
+require_relative '../mixin/errors'
+require_relative '../mixin/reflection'
+require_relative '../mixin/handler_support'
+require_relative 'parameter'
+
+module AMA
+  module Entity
+    class Mapper
+      class Type
+        # Stores data about single type attribute
+        class Attribute
+          include Mixin::Errors
+          include Mixin::Reflection
+          include Mixin::HandlerSupport
+
+          # @!attribute
+          #   @return [AMA::Entity::Mapper::Type]
+          attr_accessor :owner
+          # @!attribute
+          #   @return [Symbol]
+          attr_accessor :name
+          # @!attribute types List of possible types attribute may take
+          #   @return [Array<AMA::Entity::Mapper::Type>]
+          attr_accessor :types
+          # If attribute is declared as virtual, it is omitted from all
+          # automatic actions, such enumeration, normalization and
+          # denormalization. Main motivation behind virtual attributes was
+          # collections problem: collection can't be represented as hash of
+          # attributes, however, virtual attribute may describe collection
+          # content.
+          #
+          # @!attribute virtual
+          #   @return [TrueClass, FalseClass]
+          attr_accessor :virtual
+          # If set to true, this attribute will be omitted during normalization
+          # and won't be present in resulting structure.
+          #
+          # @!attribute sensitive
+          #   @return [TrueClass, FalseClass]
+          attr_accessor :sensitive
+          # Default value that is set on automatic object creation.
+          #
+          # @!attribute default
+          #   @return [Object]
+          attr_accessor :default
+          # Whether or not this attribute may be represented by null.
+          #
+          # @!attribute nullable
+          #   @return [TrueClass, FalseClass]
+          attr_accessor :nullable
+          # List of values this attribute acceptable to take. Part of automatic
+          # validation.
+          #
+          # @!attribute values
+          #   @return [Array<Object>]
+          attr_accessor :values
+          # @!attribute aliases
+          #   @return [Array<Symbol>]
+          attr_accessor :aliases
+
+          handler_namespace Handler::Attribute
+
+          # Custom attribute validator
+          #
+          # @!attribute validator
+          #   @return [API::AttributeValidator]
+          handler :validator, :validate
+
+          def self.defaults
+            {
+              virtual: false,
+              sensitive: false,
+              default: nil,
+              nullable: false,
+              values: [],
+              validator: nil,
+              aliases: []
+            }
+          end
+
+          # @param [Mapper::Type] owner
+          # @param [Symbol] name
+          # @param [Array<Mapper::Type>] types
+          # @param [Hash<Symbol, Object] options
+          def initialize(owner, name, *types, **options)
+            @owner = validate_owner!(owner)
+            @name = validate_name!(name)
+            @types = validate_types!(types)
+            self.class.defaults.each do |key, value|
+              value = options.fetch(key, value)
+              unless value.nil?
+                set_object_attribute(self, key, options.fetch(key, value))
+              end
+            end
+          end
+
+          def violations(value, context)
+            validator.validate(value, self, context)
+          end
+
+          def valid?(value, context)
+            violations(value, context).empty?
+          end
+
+          def valid!(value, context)
+            violations = self.violations(value, context)
+            return if violations.empty?
+            repr = violations.join(', ')
+            message = "Attribute #{self} has failed validation: #{repr}"
+            validation_error(message, context: context)
+          end
+
+          def resolved?
+            types.all?(&:resolved?)
+          end
+
+          def resolved!(context = nil)
+            types.each { |type| type.resolved!(context) }
+          end
+
+          # @param [AMA::Entity::Mapper::Type] parameter
+          # @param [AMA::Entity::Mapper::Type] substitution
+          # @return [AMA::Entity::Mapper::Type::Attribute]
+          def resolve_parameter(parameter, substitution)
+            clone.tap do |clone|
+              clone.types = types.each_with_object([]) do |type, carrier|
+                if type == parameter
+                  buffer = substitution
+                  buffer = [buffer] unless buffer.is_a?(Enumerable)
+                  next carrier.push(*buffer)
+                end
+                carrier.push(type.resolve_parameter(parameter, substitution))
+              end
+            end
+          end
+
+          def hash
+            @owner.hash ^ @name.hash
+          end
+
+          def eql?(other)
+            return false unless other.is_a?(self.class)
+            @owner == other.owner && @name == other.name
+          end
+
+          def ==(other)
+            eql?(other)
+          end
+
+          def to_def
+            types = @types ? @types.map(&:to_def).join(', ') : 'none'
+            message = "#{owner.type}.#{name}"
+            message += ':virtual' if virtual
+            "#{message}<#{types}>"
+          end
+
+          def to_s
+            message = "Attribute #{owner.type}.#{name}"
+            message = "#{message} (virtual)" if virtual
+            types = @types ? @types.map(&:to_def).join(', ') : 'none'
+            "#{message} <#{types}>"
+          end
+
+          private
+
+          def validate_owner!(owner)
+            return owner if owner.is_a?(Type)
+            message = 'Provided owner has to be a Type instance,' \
+              " #{owner.class} received"
+            compliance_error(message)
+          end
+
+          def validate_name!(name)
+            return name if name.is_a?(Symbol)
+            message = "Provided name has to be Symbol, #{name.class} received"
+            compliance_error(message)
+          end
+
+          def validate_types!(types)
+            compliance_error("No types provided for #{self}") if types.empty?
+            types.each do |type|
+              next if type.is_a?(Type) || type.is_a?(Parameter)
+              message = 'Provided type has to be a Type instance, ' \
+                "#{type.class} received"
+              compliance_error(message)
+            end
+          end
+        end
+      end
+    end
+  end
+end