ama-entity-mapper 0.1.0.beta.2

data/docs/index.md

@@ -0,0 +1,23 @@
+---
+layout: page
+---
+
+This is the documentation page for [ama-entity-mapper][gem] gem.
+
+AMA::Entity::Mapper is simply an API to map one data structures into 
+other minimizing manual work, like mapping humongous nested API output
+to some domain classes, or data normalization and denormalization
+before saving.
+
+## Pages
+
+1. [Installation](installation)
+2. [Basic Usage](basic-usage)
+3. [Algorithm](algorithm)
+4. [DSL In Detail](dsl)
+5. [Parametrized Types (Generics)](generics)
+6. [Wildcards](wildcards)
+7. [Handlers](handlers)
+8. [Logging](logging])
+
+  [gem]: https://rubygems.org/gems/ama-entity-mapper

data/docs/installation.md

@@ -0,0 +1,27 @@
+---
+title: Installation
+---
+
+Installation is terribly simple - it's a gem, after all. You can either
+install it manually
+
+```bash
+gem ama-entity-mapper
+```
+
+or leave it up do Bundler:
+
+```bash
+echo "gem 'ama-entity-mapper'" >> Gemfile
+bundle install
+```
+
+All what's left is to require the gem in code and start using it:
+
+```ruby
+require 'ama-entity-mapper'
+
+# ...
+
+value = AMA::Entity::Mapper.map(input, type)
+```

data/docs/logging.md

@@ -0,0 +1,18 @@
+---
+title: Logging
+---
+
+Mapper can have complex scenarios running under the hood, and sometimes
+it is necessary to dive into them to find that your nested type is 
+specified incorrectly or somewhere nil is possible, but attribute is 
+not set as `nullable`. Mapper logs as much as it can under logger 
+provided in context. By default, it is just standard `logger` instance 
+that thrashes it's input instantly, but you can easily substitute that
+by specifying logger as a keyword parameter:
+
+```ruby
+AMA::Entity::Mapper.map(input, type, logger: logger)
+AMA::Entity::Mapper.normalize(entity, logger: logger)
+```
+
+Logger is available through `context.logger` in custom handlers.

data/docs/wildcards.md

@@ -0,0 +1,16 @@
+---
+title: Wildcards (Any Type)
+---
+
+Sometimes it is necessary not to do processing at all. to do so, use
+`Any` type:
+
+```ruby
+wildcard = AMA::Entity::Mapper::Type::Any::INSTANCE
+type = [Enumerable, T: [Float, Integer, wildcard, NilClass]]
+
+AMA::Entity::Mapper.map(input, type)
+```
+
+Please note that `Any` doesn't match nils. If you need to match nils, 
+just add `NilClass` to type collection.

data/lib/ama-entity-mapper.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'ama-entity-mapper/version'
+require_relative 'ama-entity-mapper/engine'
+require_relative 'ama-entity-mapper/type'
+require_relative 'ama-entity-mapper/type/registry'
+require_relative 'ama-entity-mapper/dsl'
+
+module AMA
+  module Entity
+    # Entrypoint class which provides basic user access
+    class Mapper
+      class << self
+        attr_writer :engine
+
+        def engine
+          @engine ||= Engine.new(Type::Registry.new.with_default_types)
+        end
+
+        def types
+          engine.registry
+        end
+
+        def resolve(definition)
+          engine.resolve(definition)
+        end
+
+        def map(input, *types, **options)
+          engine.map(input, *types, **options)
+        end
+
+        def normalize(input, **options)
+          engine.normalize(input, **options)
+        end
+
+        def [](klass)
+          engine.registry[klass]
+        end
+      end
+    end
+  end
+end

data/lib/ama-entity-mapper/aux/null_stream.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module AMA
+  module Entity
+    class Mapper
+      module Aux
+        # :nocov:
+        # I just did copy-paste from SO
+        # https://stackoverflow.com/a/8681953/2908793
+        #
+        # This class is required to use logger without any real output backend,
+        # which is by default
+        class NullStream
+          INSTANCE = new
+
+          def write(message, *)
+            message.size
+          end
+
+          def close(*); end
+
+          def <<(*)
+            self
+          end
+        end
+        # :nocov:
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+require_relative 'path'
+require_relative 'mixin/reflection'
+require_relative 'aux/null_stream'
+
+module AMA
+  module Entity
+    class Mapper
+      # Base class for various contexts, created to define common ground for
+      # any traversal operations
+      class Context
+        include Mixin::Reflection
+
+        # @!attribute [r] path
+        #   @return [AMA::Entity::Mapper::Path]
+        attr_reader :path
+        # @!attribute [r] logger
+        #   @return [Logger]
+        attr_reader :logger
+        # @!attribute [r] strict
+        #   @return [FalseClass, TrueClass]
+        attr_reader :strict
+
+        def initialize(**options)
+          defaults = respond_to?(:defaults) ? self.defaults : {}
+          options = defaults.merge(options)
+          defaults.keys.each do |key|
+            instance_variable_set("@#{key}", options[key])
+          end
+          @logger = @logger.clone
+          @logger.progname = "#{Mapper} #{path}"
+        end
+
+        def defaults
+          {
+            path: Path.new,
+            logger: Logger.new(Aux::NullStream::INSTANCE),
+            strict: true
+          }
+        end
+
+        # Creates new context, resembling traversal to specified segment
+        #
+        # @param [AMA::Entity::Mapper::Path::Segment, String, Symbol] segment
+        # @return [AMA::Entity::Mapper::Context]
+        def advance(segment)
+          return self if segment.nil?
+          data = to_h.merge(path: path.push(segment))
+          self.class.new(**data)
+        end
+
+        def to_h
+          object_variables(self)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'dsl/class_methods'
+
+module AMA
+  module Entity
+    class Mapper
+      # Entrypoint module for inclusion in target entities
+      module DSL
+        class << self
+          def included(klass)
+            klass.singleton_class.instance_eval do
+              include ClassMethods
+            end
+            klass.engine = Mapper.engine
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ama-entity-mapper/dsl/class_methods.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative '../mixin/reflection'
+require_relative '../handler/entity/factory'
+require_relative '../handler/entity/enumerator'
+require_relative '../handler/entity/injector'
+require_relative '../handler/entity/normalizer'
+require_relative '../handler/entity/denormalizer'
+require_relative '../handler/entity/validator'
+require_relative '../type'
+require_relative '../type/any'
+require_relative '../type/parameter'
+
+module AMA
+  module Entity
+    class Mapper
+      module DSL
+        # Module providing DSL methods for entity class
+        module ClassMethods
+          include Mixin::Reflection
+
+          def engine=(engine)
+            @engine = engine
+            engine.register(self)
+            engine
+          end
+
+          def engine
+            self.engine = Mapper.engine unless @engine
+            @engine
+          end
+
+          # @return [AMA::Entity::Mapper::Type]
+          def bound_type
+            engine[self]
+          end
+
+          # @param [String, Symbol] name
+          # @param [Array<AMA::Entity::Mapper::Type] types List of possible
+          #   attribute types
+          # @param [Hash] options Attribute options:
+          # @option options [TrueClass, FalseClass] virtual
+          # @option options [TrueClass, FalseClass] sensitive
+          # @option options [TrueClass, FalseClass] nullable
+          # @option options [Object] default
+          # @option options [Array] values
+          # @return [AMA::Entity::Mapper::Type::Attribute]
+          def attribute(name, *types, **options)
+            types = types.map(&method(:resolve_type))
+            types = [Type::Any::INSTANCE] if types.empty?
+            bound_type.attribute!(name, *types, **options)
+            define_method(name) do
+              instance_variable_get("@#{name}")
+            end
+            define_method("#{name}=") do |value|
+              instance_variable_set("@#{name}", value)
+            end
+          end
+
+          # Returns parameter reference
+          #
+          # @param [String, Symbol] id
+          # @return [AMA::Entity::Mapper::Type::Parameter]
+          def parameter(id)
+            bound_type.parameter!(id)
+          end
+
+          handlers = {
+            factory: :create,
+            enumerator: :enumerate,
+            injector: :inject,
+            normalizer: :normalize,
+            denormalizer: :denormalize,
+            validator: :validate
+          }
+          handlers.each do |name, method_name|
+            setter_name = "#{name}="
+            define_method setter_name do |handler|
+              wrapper = Handler::Entity.const_get(name.capitalize).wrap(handler)
+              bound_type.send(setter_name, wrapper)
+            end
+
+            define_method "#{name}_block" do |&block|
+              send(setter_name, method_object(method_name, &block))
+            end
+          end
+
+          private
+
+          def resolve_type(type)
+            return Type::Any::INSTANCE if type.nil? || type == :*
+            return parameter(type) if type.is_a?(Symbol) || type.is_a?(String)
+            return type if type.is_a?(Type::Parameter)
+            engine.resolve(type)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative 'path'
+require_relative 'context'
+require_relative 'error'
+require_relative 'mixin/errors'
+require_relative 'mixin/suppression_support'
+require_relative 'type'
+require_relative 'type/registry'
+require_relative 'type/resolver'
+require_relative 'type/analyzer'
+require_relative 'engine/recursive_mapper'
+require_relative 'engine/recursive_normalizer'
+
+module AMA
+  module Entity
+    class Mapper
+      # Main, user-unfriendly, library-entrypoint class. Provides interface for
+      # mapping one type into another.
+      class Engine
+        include Mixin::Errors
+
+        # @!attribute [r] registry
+        #   @return [Type::Registry]
+        attr_reader :registry
+        # @!attribute [r] resolver
+        #   @return [Type::Resolver]
+        attr_reader :resolver
+
+        # @param [Type::Registry] registry
+        def initialize(registry = nil)
+          @registry = registry || Type::Registry.new
+          @resolver = Type::Resolver.new(@registry)
+          @normalizer = RecursiveNormalizer.new(@registry)
+          @mapper = RecursiveMapper.new(@registry)
+        end
+
+        # @param [Object] source
+        # @param [Array<AMA::Entity::Mapper::Type>] types
+        # @param [Hash] context_options
+        def map(source, *types, **context_options)
+          context = create_context(context_options)
+          types = normalize_types(types, context)
+          @mapper.map(source, types, context)
+        end
+
+        # Resolves provided definition, creating type hierarchy.
+        # @param [Array<Class, Module, Type, Array>] definition
+        def resolve(definition)
+          @resolver.resolve(definition)
+        end
+
+        # Normalizes object to primitive data structures.
+        # @param [Object] object
+        # @param [Hash] context_options
+        def normalize(object, **context_options)
+          @normalizer.normalize(object, create_context(context_options))
+        end
+
+        # @param [Class, Module] klass
+        def register(klass)
+          @registry[klass] || @registry.register(Type::Analyzer.analyze(klass))
+        end
+
+        # @param [Class, Module] klass
+        def [](klass)
+          @registry[klass]
+        end
+
+        private
+
+        # @param [Hash] options
+        # @return [AMA::Entity::Mapper::Engine::Context]
+        def create_context(options)
+          options = options.merge(path: Path.new)
+          Mapper::Context.new(**options)
+        end
+
+        # @param [Array<AMA::Entity::Mapper::Type>] types
+        def normalize_types(types, context)
+          compliance_error('Called #map() with no types') if types.empty?
+          types = types.map { |type| @resolver.resolve(type) }
+          types.each { |type| type.resolved!(context) }
+        end
+      end
+    end
+  end
+end

data/lib/ama-entity-mapper/engine/recursive_mapper.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative '../mixin/suppression_support'
+require_relative '../mixin/errors'
+require_relative '../error'
+require_relative '../type'
+require_relative '../type/analyzer'
+
+module AMA
+  module Entity
+    class Mapper
+      class Engine
+        # Recursively maps object to one of specified types
+        class RecursiveMapper
+          include Mixin::SuppressionSupport
+          include Mixin::Errors
+
+          # @param [AMA::Entity::Mapper::Type::Registry] registry
+          def initialize(registry)
+            @registry = registry
+          end
+
+          # @param [Object] source
+          # @param [Array<AMA::Entity::Mapper::Type] types
+          # @param [AMA::Entity::Mapper::Context] context
+          def map(source, types, context)
+            map_unsafe(source, types, context)
+          rescue StandardError => e
+            message = "Failed to map #{source.class} " \
+              "to any of provided types (#{types.map(&:to_def).join(', ')}). " \
+              "Last error: #{e.message} in #{e.backtrace_locations[0]}"
+            mapping_error(message)
+          end
+
+          # @param [Object] source
+          # @param [AMA::Entity::Mapper::Type] type
+          # @param [AMA::Entity::Mapper::Context] ctx
+          # @return [Object]
+          def map_type(source, type, ctx)
+            ctx.logger.debug("Mapping #{source.class} to type #{type.to_def}")
+            source, reassembled = request_reassembly(source, type, ctx)
+            epithet = reassembled ? 'reassembled' : 'source'
+            if type.attributes.empty?
+              message = "#{type.to_def} has no attributes, " \
+                "returning #{epithet} instance"
+              ctx.logger.debug(message)
+              return source
+            end
+            process_attributes(source, type, ctx)
+          end
+
+          private
+
+          # @param [Object] source
+          # @param [Array<AMA::Entity::Mapper::Type] types
+          # @param [AMA::Entity::Mapper::Context] context
+          def map_unsafe(source, types, context)
+            message = "Mapping #{source.class} into one of: " \
+              "#{types.map(&:to_def).join(', ')}"
+            context.logger.debug(message)
+            successful(types, Mapper::Error, context) do |type|
+              result = map_type(source, type, context)
+              context.logger.debug("Validating resulting #{type.to_def}")
+              type.valid!(result, context)
+              result
+            end
+          end
+
+          # @param [Object] source
+          # @param [AMA::Entity::Mapper::Type] type
+          # @param [AMA::Entity::Mapper::Context] ctx
+          # @return [Object]
+          def process_attributes(source, type, ctx)
+            attributes = map_attributes(source, type, ctx)
+            if attributes.select(&:first).empty?
+              message = 'No changes in attributes detected, ' \
+                "returning #{source.class}"
+              ctx.logger.debug(message)
+              return source
+            end
+            ctx.logger.debug("Creating new #{type.to_def} instance")
+            target = type.factory.create(type, source, ctx)
+            ctx.logger.debug("Installing #{type.to_def} attributes")
+            install_attributes(target, type, attributes, ctx)
+          end
+
+          # Returns array of mapped attribute in format
+          # [[changed?, attribute, value, attribute_context],..]
+          # @param [Object] source
+          # @param [AMA::Entity::Mapper::Type] type
+          # @param [AMA::Entity::Mapper::Context] ctx
+          # @return [Array]
+          def map_attributes(source, type, ctx)
+            ctx.logger.debug("Mapping #{source.class} attributes")
+            enumerator = type.enumerator.enumerate(source, type, ctx)
+            enumerator.map do |attribute, value, segment|
+              local_ctx = segment.nil? ? ctx : ctx.advance(segment)
+              mutated = map_attribute(value, attribute, local_ctx)
+              changed = !mutated.equal?(value)
+              if changed
+                ctx.logger.debug("Attribute #{attribute.to_def} has changed")
+              end
+              [changed, attribute, mutated, local_ctx]
+            end
+          end
+
+          # @param [Object] source
+          # @param [AMA::Entity::Mapper::Type::Attribute] attribute
+          # @param [AMA::Entity::Mapper::Context] context
+          def map_attribute(source, attribute, context)
+            message = "Extracting attribute #{attribute.to_def} " \
+              "from #{source.class}"
+            context.logger.debug(message)
+            successful(attribute.types, Mapper::Error) do |type|
+              if source.nil? && attribute.nullable
+                context.logger.debug('Found legal nil, short-circuiting')
+                break nil
+              end
+              result = map_type(source, type, context)
+              context.logger.debug("Validating resulting #{attribute.to_def}")
+              attribute.valid!(result, context)
+              result
+            end
+          end
+
+          # @param [Object] target
+          # @param [AMA::Entity::Mapper::Type] type
+          # @param [Array] attributes
+          # @param [AMA::Entity::Mapper::Context] ctx
+          def install_attributes(target, type, attributes, ctx)
+            ctx.logger.debug("Installing updated attributes on #{type.to_def}")
+            attributes.each do |_, attribute, value, local_ctx|
+              type.injector.inject(target, type, attribute, value, local_ctx)
+            end
+            target
+          end
+
+          # @param [Object] source
+          # @param [AMA::Entity::Mapper::Type] type
+          # @param [AMA::Entity::Mapper::Context] context
+          # @return [Array<Object, TrueClass, FalseClass>]
+          def request_reassembly(source, type, context)
+            # TODO: make reassembly optional
+            reassemble(source, type, context)
+          end
+
+          # @param [Object] source
+          # @param [AMA::Entity::Mapper::Type] type
+          # @param [AMA::Entity::Mapper::Context] context
+          # @return [Object]
+          def reassemble(source, type, context)
+            message = "Reassembling #{source.class} as #{type.type}"
+            context.logger.debug(message)
+            source_type = @registry.find(source.class)
+            source_type ||= Type::Analyzer.analyze(source.class)
+            normalizer = source_type.normalizer
+            normalized = normalizer.normalize(source, source_type, context)
+            [type.denormalizer.denormalize(normalized, type, context), true]
+          end
+        end
+      end
+    end
+  end
+end