remap 2.0.3 → 2.1.0

data/lib/remap/constructor/argument.rb

@@ -2,16 +2,27 @@
 
 module Remap
   class Constructor
-    class Argument < Concrete
-      using State::Extension
+    using State::Extension
 
+    # Allows a class (target) to be called with a regular argument
+    class Argument < Concrete
+      # @return [:argument]
       attribute :strategy, Value(:argument), default: :argument
 
-      # Uses the {#method} method to initialize {#target} with {state}
-      # Target is only called if {state} is defined
+      # Uses the {#method} method to initialize {#target} with state
+      # Target is only called if state is defined
+      #
+      # Used by {Remap::Base} to define constructors for mapped data
       #
       # Fails if {#target} does not respond to {#method}
-      # Fails if {#target} cannot be called with {state}
+      # Fails if {#target} cannot be called with state
+      #
+      # @example Initialize a target with a state
+      #   target = ::Struct.new(:foo)
+      #   constructor = Remap::Constructor.call(strategy: :argument, target: target, method: :new)
+      #   state = Remap::State.call(:bar)
+      #   new_state = constructor.call(state)
+      #   new_state.fetch(:value).foo # => :bar
       #
       # @param state [State]
       #
@@ -20,7 +31,10 @@ module Remap
         super.fmap do |input|
           target.public_send(id, input)
         rescue ArgumentError => e
-          raise e.exception("Could not load target [#{target}] using the argument strategy with [#{input}] (#{input.class})")
+          raise e.exception("Failed to create [%p] with input [%s] (%s)" % [
+            target, input,
+            input.class
+          ])
         end
       end
     end

data/lib/remap/constructor/keyword.rb

@@ -2,15 +2,26 @@
 
 module Remap
   class Constructor
-    class Keyword < Concrete
-      using State::Extension
+    using State::Extension
 
+    # Allows a class (target) to be called with keyword arguments
+    class Keyword < Concrete
+      # @return [:keyword]
       attribute :strategy, Value(:keyword)
 
       # Calls {#target} as with keyword arguments
       #
       # Fails if {#target} does not respond to {#method}
-      # Fails if {#target} cannot be called with {state}
+      # Fails if {#target} cannot be called with state
+      #
+      # Used by {Remap::Base} to define constructors for mapped data
+      #
+      # @example Initialize a target with a state
+      #   target = OpenStruct
+      #   constructor = Remap::Constructor.call(strategy: :keyword, target: target, method: :new)
+      #   state = Remap::State.call({ foo: :bar })
+      #   new_state = constructor.call(state)
+      #   new_state.fetch(:value).foo # => :bar
       #
       # @param state [State]
       #
@@ -23,7 +34,12 @@ module Remap
 
           target.public_send(id, **input)
         rescue ArgumentError => e
-          raise e.exception("Could not load target [#{target}] using the keyword strategy using [#{input}] (#{input.class})")
+          raise e.exception("Failed to create [%p] with input [%s] (%s}) using method %s" % [
+            target,
+            input,
+            input.class,
+            id
+          ])
         end
       end
     end

data/lib/remap/constructor/none.rb

@@ -2,15 +2,14 @@
 
 module Remap
   class Constructor
+    # Default type used by {Remap::Base}
     class None < Concrete
       attribute :target, Types::Nothing
       attribute :strategy, Types::Any
       attribute :method, Types::Any
 
-      # Just returns the input state
-      #
-      # Fails if {#target} does not respond to {#method}
-      # Fails if {#target} cannot be called with {state}
+      # Used by {Remap::Base} as a default constructor
+      # Using it does nothing but return its input state
       #
       # @param state [State]
       #

data/lib/remap/constructor.rb

@@ -2,8 +2,11 @@
 
 module Remap
   class Constructor < Dry::Interface
+    # @return [Any]
+    attribute :target, Types::Any, not_eql: Nothing
+
+    # @return [Symbol]
     attribute :method, Symbol, default: :new
-    attribute :target, Types::Any.constrained(not_eql: Nothing)
 
     # Ensures {#target} responds to {#method}
     # Returns an error state unless above is true
@@ -19,12 +22,16 @@ module Remap
       end
     end
 
-    def id
-      attributes.fetch(:method)
-    end
-
+    # @return [Proc]
     def to_proc
       method(:call).to_proc
     end
+
+    private
+
+    # @return [Symbol]
+    def id
+      attributes.fetch(:method)
+    end
   end
 end

data/lib/remap/contract.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Remap
+  class Contract < Dry::Validation::Contract
+    # Constructs a contract used to validate mapper input
+    #
+    # @param rules [Array<Proc>]
+    # @param options [Hash]
+    # @param contract [Proc]
+    # @param attributes [Hash]
+    #
+    # @return [Contract]
+    def self.call(rules:, options:, contract:, attributes:)
+      Class.new(self) do
+        rules.each do |rule|
+          class_eval(&rule)
+        end
+
+        options.each do |option|
+          class_eval(&option)
+        end
+
+        schema(contract)
+      end.new(**attributes)
+    end
+  end
+end

data/lib/remap/extensions/enumerable.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Remap
+  module Extensions
+    using Object
+
+    module Enumerable
+      refine ::Enumerable do
+        # Creates a hash using {self} as the {path} and {value} as the hash value
+        #
+        # @param value [Any] Hash value
+        #
+        # @example A hash from path
+        #   [:a, :b].hide('value') # => { a: { b: 'value' } }
+        #
+        # @return [Hash]
+        def hide(value)
+          reverse.reduce(value) do |element, key|
+            { key => element }
+          end
+        end
+
+        # Fetches value at {path}
+        #
+        # @example Fetch value at path
+        #   [[:a, :b], [:c, :d]].get(0, 1) # => :b
+        #
+        # @return [Any]
+        #
+        # @raise When path cannot be found
+        def get(*path, &error)
+          _, result = path.reduce([
+            EMPTY_ARRAY,
+            self
+          ]) do |(current_path, element), key|
+            value = element.fetch(key) do
+              raise PathError, current_path + [key]
+            end
+
+            [current_path + [key], value]
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/remap/extensions/hash.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Remap
+  module Extensions
+    module Hash
+      refine ::Hash do
+        def formated
+          JSON.neat_generate(self, sort: true, wrap: 40, aligned: true, around_colon: 1)
+        end
+      end
+    end
+  end
+end

data/lib/remap/extensions/object.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Remap
+  module Extensions
+    module Object
+      refine ::Object do
+        # Fallback validation method
+        #
+        # @yield if block is provided
+        #
+        # @raise unless block is provided
+        def _(&block)
+          unless block
+            return _ { raise _1 }
+          end
+
+          block["Expected a state, got [#{self}] (#{self.class})"]
+        end
+
+        # Fallback method used when #get is called on an object that does not respond to #get
+        #
+        # Block is invoked, if provided
+        # Otherwise a symbol is thrown
+        #
+        # @param path [Array<Key>]
+        def get(*path, &block)
+          raise PathError, []
+        end
+        alias_method :fetch, :get
+
+        def formated
+          self
+        end
+      end
+    end
+  end
+end

data/lib/remap/failure.rb

@@ -1,27 +1,37 @@
 # frozen_string_literal: true
 
 module Remap
-  class Failure < Result
-    attribute :reasons, Types::Hash
+  using Extensions::Hash
 
-    def inspect
-      format("Failure<[%<result>s]>", result: JSON.pretty_generate(to_h))
-    end
+  class Failure < Dry::Concrete
+    attribute :failures, [Notice], min_size: 1
+    attribute? :notices, [Notice], default: EMPTY_ARRAY
 
-    def to_hash
-      { failure: reasons, problems: problems }
-    end
+    # Merges two failures
+    #
+    # @param other [Failure]
+    #
+    # @return [Failure]
+    def merge(other)
+      unless other.is_a?(self.class)
+        raise ArgumentError, "can't merge #{self.class} with #{other.class}"
+      end
 
-    def failure?(*)
-      true
-    end
+      failure = attributes.deep_merge(other.attributes) do |_, value1, value2|
+        case [value1, value2]
+        in [Array, Array]
+          value1 + value2
+        else
+          raise ArgumentError, "can't merge #{self.class} with #{other.class}"
+        end
+      end
 
-    def success?(*)
-      false
+      new(failure)
     end
 
-    def fmap
-      self
+    # @return [String]
+    def exception
+      Error.new(attributes.formated)
     end
   end
 end

data/lib/remap/iteration/array.rb

@@ -2,28 +2,37 @@
 
 module Remap
   class Iteration
+    using State::Extension
+
+    # Implements an array iterator which defines index in state
     class Array < Concrete
-      using State::Extension
+      # @return [Array<T>]
+      attribute :value, Types::Array, alias: :array
 
-      attribute :value, Types::Array
+      # @return [State<Array<T>>]
       attribute :state, Types::State
 
-      def map(&block)
-        value.each_with_index.reduce(init) do |input_state, (value, index)|
-          block[value, index: index]._.then do |new_state|
-            new_state.fmap { [_1] }
-          end.then do |new_array_state|
-            input_state.merged(new_array_state)
-          end
-        end._
+      # @see Iteration#map
+      def call(&block)
+        array.each_with_index.reduce(init) do |state, (value, index)|
+          reduce(state, value, index, &block)
+        end
       end
-      alias call map
 
       private
 
       def init
         state.set(EMPTY_ARRAY)
       end
+
+      def reduce(state, value, index, &block)
+        notice = catch :ignore do
+          other = block[value, index: index]
+          return state.combine(other.fmap { [_1] })
+        end
+
+        state.set(notice: notice)
+      end
     end
   end
 end

data/lib/remap/iteration/hash.rb

@@ -2,26 +2,34 @@
 
 module Remap
   class Iteration
+    using State::Extension
+
+    # Implements a hash iterator which defines key in state
     class Hash < Concrete
-      attribute :value, Types::Hash
+      # @return [Hash]
+      attribute :value, Types::Hash, alias: :hash
+
+      # @return [State<Hash>]
       attribute :state, Types::State
 
-      using State::Extension
-
-      # @see Base#map
-      def map(&block)
-        value.reduce(init) do |input_state, (key, value)|
-          block[value, key: key]._.then do |new_state|
-            new_state.fmap { { key => _1 } }
-          end.then do |new_hash_state|
-            input_state.merged(new_hash_state)
-          end
-        end._
+      # @see Iteration#map
+      def call(&block)
+        hash.reduce(init) do |state, (key, value)|
+          reduce(state, key, value, &block)
+        end
       end
-      alias call map
 
       private
 
+      def reduce(state, key, value, &block)
+        notice = catch :ignore do
+          other = block[value, key: key]
+          return state.combine(other.fmap { { key => _1 } })
+        end
+
+        state.set(notice: notice)
+      end
+
       def init
         state.set(EMPTY_HASH)
       end

data/lib/remap/iteration/other.rb

@@ -2,17 +2,17 @@
 
 module Remap
   class Iteration
+    using State::Extension
+
+    # Default iterator which doesn't do anything
     class Other < Concrete
+      attribute :value, Types::Any, alias: :other
       attribute :state, Types::State
-      attribute :value, Types::Any
-
-      using State::Extension
 
-      # @see Base#map
-      def map(&block)
-        block[value]._
+      # @see Iteration#map
+      def call(&block)
+        state.fatal!("Expected an enumerable, got %s (%s)", value, value.class)
       end
-      alias call map
     end
   end
 end

data/lib/remap/iteration.rb

@@ -2,10 +2,13 @@
 
 module Remap
   class Iteration < Dry::Interface
-    attribute :value, Types::Value
+    # @return [State<T>]
     attribute :state, Types::State
 
-    # Maps every element in {#value} to {#block}
+    # @return [T]
+    attribute :value, Types::Any
+
+    # Maps every element in {#value}
     #
     # @abstract
     #
@@ -14,6 +17,9 @@ module Remap
     # @yieldreturn [Array<V>, Hash<V, K>]
     #
     # @return [Array<V>, Hash<V, K>]
+    def call(state)
+      raise NotImplementedError, "#{self.class}#call not implemented"
+    end
 
     order :Hash, :Array, :Other
   end

data/lib/remap/mapper/and.rb

@@ -2,14 +2,36 @@
 
 module Remap
   class Mapper
-    class And < Binary
-      using State::Extension
+    using State::Extension
 
+    # Represents two mappers that are combined with the & operator
+    #
+    # @example Combine two mappers
+    #   class Mapper1 < Remap::Base
+    #     contract do
+    #       required(:a1)
+    #     end
+    #   end
+    #
+    #   class Mapper2 < Remap::Base
+    #     contract do
+    #       required(:a2)
+    #     end
+    #   end
+    #
+    #   state = Remap::State.call({ a2: 2, a1: 1 })
+    #   output = (Mapper1 & Mapper2).call!(state)
+    #   output.fetch(:value) # => { a2: 2, a1: 1 }
+    class And < Binary
+      # Succeeds if both left and right succeed
+      # Returns the combined result of left and right
+      #
+      # @param state [State]
+      #
+      # @yield [Failure] if mapper fails
+      #
+      # @return [Result]
       def call!(state, &error)
-        unless error
-          return call!(state, &exception)
-        end
-
         state1 = left.call!(state) do |failure1|
           right.call!(state) do |failure2|
             return error[failure1.merge(failure2)]
@@ -22,7 +44,7 @@ module Remap
           return error[failure]
         end
 
-        state1.merged(state2)
+        state1.combine(state2)
       end
     end
   end

data/lib/remap/mapper/binary.rb

@@ -2,15 +2,12 @@
 
 module Remap
   class Mapper
+    # @abstract
     class Binary < self
+      include Operation
+
       attribute :left, Types::Mapper
       attribute :right, Types::Mapper
-
-      def exception
-        ->(error) { raise error }
-      end
-
-      include Operation
     end
   end
 end

data/lib/remap/mapper/or.rb

@@ -2,14 +2,37 @@
 
 module Remap
   class Mapper
-    class Or < Binary
-      using State::Extension
+    using State::Extension
 
+    # Represents two mappers that are combined with the | operator
+    #
+    # @example Combine two mappers
+    #   class Mapper1 < Remap::Base
+    #     contract do
+    #       required(:a1)
+    #     end
+    #   end
+    #
+    #   class Mapper2 < Remap::Base
+    #     contract do
+    #       required(:a2)
+    #     end
+    #   end
+    #
+    #   state = Remap::State.call({ a2: 2 })
+    #   result = (Mapper1 | Mapper2).call!(state)
+    #   result.fetch(:value) # => { a2: 2 }
+    class Or < Binary
+      # Succeeds if left or right succeeds
+      # Returns which ever succeeds first
+      #
+      # @param state [State]
+      #
+      # @yieldparam [Failure] if mapper fails
+      # @yieldreturn [Failure]
+      #
+      # @return [Result]
       def call!(state, &error)
-        unless error
-          return call!(state, &exception)
-        end
-
         left.call!(state) do |failure1|
           return right.call!(state) do |failure2|
             return error[failure1.merge(failure2)]

data/lib/remap/mapper/support/operations.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Remap
+  class Mapper
+    module Operations
+      # Tries self and other and returns the first successful result
+      #
+      # @param other [Mapper]
+      #
+      # @return [Mapper::Or]
+      def |(other)
+        Or.new(left: self, right: other)
+      rescue Dry::Struct::Error => e
+        raise ArgumentError, e.message
+      end
+
+      # Returns a successful result when self & other are successful
+      #
+      # @param other [Mapper]
+      #
+      # @return [Mapper::And]
+      def &(other)
+        And.new(left: self, right: other)
+      rescue Dry::Struct::Error => e
+        raise ArgumentError, e.message
+      end
+
+      # Returns a successful result when only one of self & other are successful
+      #
+      # @param other [Mapper]
+      #
+      # @return [Mapper:Xor]
+      def ^(other)
+        Xor.new(left: self, right: other)
+      rescue Dry::Struct::Error => e
+        raise ArgumentError, e.message
+      end
+    end
+  end
+end

data/lib/remap/mapper/xor.rb

@@ -2,14 +2,36 @@
 
 module Remap
   class Mapper
-    class Xor < Binary
-      using State::Extension
+    using State::Extension
 
+    # Represents two mappers that are combined with the ^ operator
+    #
+    # @example Combine two mappers
+    #   class Mapper1 < Remap::Base
+    #     contract do
+    #       required(:a1)
+    #     end
+    #   end
+    #
+    #   class Mapper2 < Remap::Base
+    #     contract do
+    #       required(:a2)
+    #     end
+    #   end
+    #
+    #   state = Remap::State.call({ a2: 2 })
+    #   output = (Mapper1 ^ Mapper2).call!(state)
+    #   output.fetch(:value) # => { a2: 2 }
+    class Xor < Binary
+      # Succeeds if left or right succeeds, but not both
+      #
+      # @param state [State]
+      #
+      # @yieldparam [Failure] if mapper fails
+      # @yieldreturn [Failure]
+      #
+      # @return [Result]
       def call!(state, &error)
-        unless error
-          return call!(state, &exception)
-        end
-
         state1 = left.call!(state) do |failure1|
           return right.call!(state) do |failure2|
             return error[failure1.merge(failure2)]
@@ -20,7 +42,7 @@ module Remap
           return state1
         end
 
-        error[state1.merged(state2).failure("Both left and right passed in xor")]
+        state1.combine(state2).failure("Both left and right passed xor operation").then(&error)
       end
     end
   end