remap 2.0.3 → 2.1.6

data/lib/remap/operation.rb

@@ -1,26 +1,39 @@
 # frozen_string_literal: true
 
 module Remap
-  module Operation
-    using State::Extension
-    include State
+  using State::Extension
 
+  # Class interface for {Remap::Base} and instance interface for {Mapper}
+  module Operation
+    # Public interface for mappers
+    #
+    # @param input [Any] Data to be mapped
+    # @param options [Hash] Mapper arguments
+    #
+    # @yield [Failure] if mapper fails
+    #
+    # @return [Success] if mapper succeeds
     def call(input, **options, &error)
-      new_state = state(input, options: options, mapper: self)
-
-      new_state = call!(new_state) do |failure|
-        return Failure.new(reasons: failure, problems: new_state.problems)
+      unless error
+        return call(input, **options) do |failure|
+          raise failure.exception
+        end
       end
 
-      if error
-        return error[new_state]
+      other = State.call(input, options: options, mapper: self).then do |state|
+        call!(state) do |failure|
+          return error[failure]
+        end
       end
 
-      value = new_state.fetch(:value) do
-        return Failure.new(reasons: new_state.failure("No mapped data"), problems: new_state.problems)
+      case other
+      in { value: }
+        value
+      in { notices: [] }
+        error[other.failure("No return value")]
+      in { notices: }
+        error[Failure.call(failures: notices)]
       end
-
-      Success.new(problems: new_state.problems, result: value)
     end
   end
 end

data/lib/remap/path/input.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Remap
+  class Path
+    using State::Extension
+
+    # Returns the value at a given path
+    #
+    # @example Select "A" from { a: { b: { c: ["A"] } } }
+    #   state = Remap::State.call({ a: { b: { c: ["A"] } } })
+    #   first = Remap::Selector::Index.new(index: 0)
+    #   path = Remap::Path::Input.new([:a, :b, :c, first])
+    #
+    #   path.call(state) do |state|
+    #     state.fetch(:value)
+    #   end
+    class Input < Unit
+      # @return [Array<Selector>]
+      attribute :segments, [Selector]
+
+      # Selects the value at the path {#segments}
+      #
+      # @param state [State]
+      #
+      # @return [State]
+      def call(state, &iterator)
+        unless block_given?
+          raise ArgumentError, "Input path requires an iterator block"
+        end
+
+        segments.reverse.reduce(iterator) do |inner_iterator, selector|
+          -> inner_state { selector.call(inner_state, &inner_iterator) }
+        end.call(state)
+      end
+    end
+  end
+end

data/lib/remap/path/output.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Remap
+  class Path
+    using Extensions::Enumerable
+    using State::Extension
+
+    # Sets the value to a given path
+    #
+    # @example Maps "A" to { a: { b: { c: "A" } } }
+    #   state = Remap::State.call("A")
+    #   result = Remap::Path::Output.new([:a, :b, :c]).call(state)
+    #
+    #   result.fetch(:value) # => { a: { b: { c: "A" } } }
+    class Output < Unit
+      attribute :segments, [Types::Key]
+
+      # @return [State]
+      def call(state)
+        state.fmap do |value|
+          segments.hide(value)
+        end
+      end
+    end
+  end
+end

data/lib/remap/path.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Remap
+  # Represents a sequence of keys and selects or maps a value given a path
+  class Path < Dry::Interface
+    attribute :segments, Types::Array
+
+    delegate :>>, to: :to_proc
+
+    # @return [State]
+    #
+    # @abstract
+    def call(state)
+      raise NotImplementedError, "#{self.class}#call not implemented"
+    end
+
+    # @return [Proc]
+    def to_proc
+      method(:call).to_proc
+    end
+  end
+end

data/lib/remap/path_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Remap
+  class PathError < Error
+    # @return [Array<Key>]
+    attr_reader :path
+
+    def initialize(path)
+      super(path.join("."))
+      @path = path
+    end
+  end
+end

data/lib/remap/proxy.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Remap
+  class Proxy < ActiveSupport::ProxyObject
+    def self.const_missing(name)
+      ::Object.const_get(name)
+    end
+
+    include Dry::Core::Constants
+    extend Dry::Initializer
+
+    # See Object#tap
+    def tap(&block)
+      block[self]
+      self
+    end
+  end
+end

data/lib/remap/rule/each.rb

@@ -2,34 +2,35 @@
 
 module Remap
   class Rule
-    class Each < Value
-      using State::Extension
+    using State::Extension
 
-      attribute :rule, Types.Interface(:call)
+    # Iterates over a rule, even if the rule is not a collection
+    #
+    # @example Upcase each value in an array
+    #   state = Remap::State.call(["John", "Jane"])
+    #   upcase = Remap::Rule::Map.call({}).then(&:upcase)
+    #   each = Remap::Rule::Each.call(rule: upcase)
+    #   error = -> failure { raise failure.exception }
+    #   each.call(state, &error).fetch(:value) # => ["JOHN", "JANE"]
+    class Each < Unit
+      # @return [Rule]
+      attribute :rule, Types::Rule
 
-      # Iterates over {state} and passes each value to {rule}
-      # Restores {path} before returning state
+      # Iterates over state and passes each value to rule
+      # Restores element, key & index before returning state
       #
+      # @param state [State<Enumerable>]
       #
-      # # @example
-      #   class Mapper < Remap::Base
-      #     define do
-      #       map :people, to: :names do
-      #         each do
-      #           map(:name)
-      #         end
-      #       end
-      #     end
-      #   end
-      #
-      #   Mapper.call(people: [{ name: "John" }, { name: "Jane" }]) # => { names: ["John", "Jane"] }
-      #
-      # @param state [State]
-      #
-      # @return [State]
-      def call(state)
-        state.map do |state|
-          rule.call(state)
+      # @return [State<Enumerable>]
+      def call(state, &error)
+        unless error
+          raise ArgumentError, "Each#call(state, &error) requires a block"
+        end
+
+        state.map do |inner_state|
+          rule.call(inner_state) do |failure|
+            return error[failure]
+          end
         end
       end
     end

data/lib/remap/rule/embed.rb

@@ -2,40 +2,45 @@
 
 module Remap
   class Rule
-    class Embed < Value
-      using State::Extension
+    using State::Extension
 
+    # Embed mappers into each other
+    #
+    # @example Embed Mapper A into B
+    #   class Car < Remap::Base
+    #     define do
+    #       map :name, to: :model
+    #     end
+    #   end
+    #
+    #   class Person < Remap::Base
+    #     define do
+    #       to :person do
+    #         to :car do
+    #           embed Car
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    #   Person.call({name: "Volvo"}) # => { person: { car: { model: "Volvo" } } }
+    class Embed < Unit
+      # @return [#call!]
       attribute :mapper, Types::Mapper
 
-      # Evaluates {input} against {mapper} and returns the result
+      # Evaluates input against mapper and returns the result
       #
-      # @param state [State]
+      # @param state [State<T>]
       #
-      # @example Embed Mapper A into B
-      #   class Car < Remap::Base
-      #     define do
-      #       map :name, to: :model
-      #     end
-      #   end
-      #
-      #   class Person < Remap::Base
-      #     define do
-      #       to :person do
-      #         to :car do
-      #           embed Car
-      #         end
-      #       end
-      #     end
-      #   end
-      #
-      #   Person.call(name: "Volvo") # => { person: { car: { name: "Volvo" } } }
-      #
-      #
-      # @return [State]
-      def call(state)
-        mapper.call!(state.set(mapper: mapper)) do |error|
-          return state.problem(error)
+      # @return [State<U>]
+      def call(state, &error)
+        unless error
+          raise ArgumentError, "A block is required to evaluate the embed"
         end
+
+        mapper.call!(state.set(mapper: mapper)) do |failure|
+          return error[failure]
+        end.except(:mapper, :scope)
       end
     end
   end

data/lib/remap/rule/map/optional.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Remap
+  class Rule
+    class Map
+      using State::Extension
+
+      class Optional < Concrete
+        # Represents an optional mapping rule
+        # When the mapping fails, the value is ignored
+        #
+        # @param state [State]
+        #
+        # @return [State]
+        def call(state, &error)
+          unless error
+            raise ArgumentError, "map.call(state, &error) requires a block"
+          end
+
+          fatal(state) do
+            return ignore(state) do
+              return notice(state) do
+                return super
+              end
+            end
+          end
+        end
+
+        private
+
+        # Catches :ignore exceptions and re-package them as a state
+        #
+        # @param state [State]
+        #
+        # @return [State]
+        def ignore(state, &block)
+          state.set(notice: catch(:ignore, &block).traced(backtrace)).except(:value)
+        end
+      end
+    end
+  end
+end

data/lib/remap/rule/map/required.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Remap
+  class Rule
+    class Map
+      using State::Extension
+
+      class Required < Concrete
+        attribute :backtrace, Types::Backtrace
+
+        # Represents a required mapping rule
+        # When it fails, the entire mapping is marked as failed
+        #
+        # @param state [State]
+        #
+        # @return [State]
+        def call(state, &error)
+          unless block_given?
+            raise ArgumentError, "Required.call(state, &error) requires a block"
+          end
+
+          notice = catch :ignore do
+            return fatal(state) do
+              return notice(state) do
+                return super
+              end
+            end
+          end
+
+          error[state.failure(notice)]
+        end
+      end
+    end
+  end
+end

data/lib/remap/rule/map.rb

@@ -2,62 +2,72 @@
 
 module Remap
   class Rule
-    class Map < self
-      using State::Extension
+    using Extensions::Enumerable
+    using State::Extension
 
-      attribute :rule, Types.Interface(:call)
-      attribute :path, Path
+    # Maps an input path to an output path
+    #
+    # @example Map { name: "Ford" } to { person: { name: "Ford" } }
+    #   class Mapper < Remap::Base
+    #     define do
+    #       map :name, to: [:person, :name]
+    #     end
+    #   end
+    #
+    #   Mapper.call({ name: "Ford" }) # => { person: { name: "Ford" } }
+    class Map < Abstract
+      class Path < Struct
+        Output = Remap::Path::Output
+        Input = Remap::Path::Input
 
-      # Maps {input} in 4 steps
-      #
-      # 1. Extract value from {input} using {path}
-      # 2. For each yielded value
-      #   2.1. Map value using {#rule}
-      #   2.2. Map value using {#fn}
+        attribute :output, Output.default { Output.call(EMPTY_ARRAY) }
+        attribute :input, Input.default { Input.call(EMPTY_ARRAY) }
+      end
 
-      # @example Map :a, to :b and add 5
-      #  map = Map.new({
-      #    path: { map: :a, to: :b },
-      #    rule: Void.new,
-      #  })
-      #
-      #  map.adjust do |value|
-      #    value + 5
-      #  end
+      # @return [Hash]
+      attribute? :path, Path.default { Path.call(EMPTY_HASH) }
+
+      # @return [Rule]
+      attribute :rule, Rule.default { Void.call(EMPTY_HASH) }
+
+      # @return [Array<String>]
+      attribute? :backtrace, Types::Backtrace, default: EMPTY_ARRAY
+
+      order :Optional, :Required
+
+      # Represents a required or optional mapping rule
       #
-      #  map.call(a: 10) # => Success({ b: 15 })
+      # @param state [State]
       #
-      # @param input [Any] Value to be mapped
-      # @param state [State] Current state
+      # @return [State]
       #
-      # @return [Monad::Result]
-      def call(state)
-        path.call(state) do |inner_state|
-          rule.call(inner_state).then do |init|
-            fn.reduce(init) do |inner, fn|
-              fn[inner]
-            end
-          end
+      # @abstract
+      def call(state, &error)
+        unless error
+          raise ArgumentError, "Map#call(state, &error) requires error handler block"
+        end
+
+        notice = catch :fatal do
+          return path.input.call(state) do |inner_state|
+            rule.call(inner_state) do |failure|
+              return error[failure]
+            end.then(&callback)
+          end.then(&path.output)
         end
+
+        raise notice.traced(backtrace).exception
       end
 
-      # Post-processor for {#call}
-      #
-      # @example Add 5 to mapped value
-      #  class Mapper < Remap
-      #    define do
-      #      map.adjust do |value|
-      #        value + 5
-      #      end
-      #    end
-      #  end
-      #
-      #  Mapper.call(10) # => 15
+      # A post-processor method
       #
-      # @yieldparam value [Any] Mapped value
-      # @yieldreturn [Monad::Result, Any]
+      # @example Upcase mapped value
+      #   state = Remap::State.call("Hello World")
+      #   map = Remap::Rule::Map.call({})
+      #   upcase = map.adjust(&:upcase)
+      #   error = -> failure { raise failure.exception }
+      #   upcase.call(state, &error).fetch(:value) # => "HELLO WORLD"
       #
-      # @return [void]
+      # @return [Map]
       def adjust(&block)
         add do |state|
           state.execute(&block)
@@ -65,45 +75,156 @@ module Remap
       end
       alias then adjust
 
+      # A pending rule
+      #
+      # @param reason [String]
+      #
+      # @example Pending mapping
+      #   state = Remap::State.call(:value)
+      #   map = Remap::Rule::Map.call({})
+      #   pending = map.pending("this is pending")
+      #   error = -> failure { raise failure.exception }
+      #   pending.call(state, &error).key?(:value) # => false
+      #
+      # @return [Map]
       def pending(reason = "Pending mapping")
         add do |state|
-          state.problem(reason)
+          state.notice!(reason)
         end
       end
 
+      # An enumeration processor
+      #
+      # @example A mapped enum
+      #   enum = Remap::Rule::Map.call({}).enum do
+      #     value "A", "B"
+      #     otherwise "C"
+      #   end
+      #
+      #   error = -> failure { raise failure.exception }
+      #
+      #   a = Remap::State.call("A")
+      #   enum.call(a, &error).fetch(:value) # => "A"
+      #
+      #   b = Remap::State.call("B")
+      #   enum.call(b, &error).fetch(:value) # => "B"
+      #
+      #   c = Remap::State.call("C")
+      #   enum.call(c, &error).fetch(:value) # => "C"
+      #
+      #   d = Remap::State.call("D")
+      #   enum.call(d, &error).fetch(:value) # => "C"
+      #
+      # @return [Map]
       def enum(&block)
-        add do |state|
-          state.fmap do |id, &error|
-            Enum.call(&block).get(id, &error)
+        add do |outer_state|
+          outer_state.fmap do |id, state|
+            Enum.call(&block).get(id) do
+              state.ignore!("Enum value %p (%s) not defined", id, id.class)
+            end
           end
         end
       end
 
+      # Keeps map, only if block is true
+      #
+      # @example Keep if value contains "A"
+      #   map = Remap::Rule::Map.call({}).if do
+      #     value.include?("A")
+      #   end
+      #
+      #   error = -> failure { raise failure.exception }
+      #
+      #   a = Remap::State.call("A")
+      #   map.call(a, &error).fetch(:value) # => "A"
+      #
+      #   b = Remap::State.call("BA")
+      #   map.call(b, &error).fetch(:value) # => "BA"
+      #
+      #   c = Remap::State.call("C")
+      #   map.call(c, &error).key?(:value) # => false
+      #
+      # @return [Map]
       def if(&block)
-        add do |state|
-          state.execute(&block).fmap do |bool, &error|
-            bool ? state.value : error["#if returned false"]
+        add do |outer_state|
+          outer_state.execute(&block).fmap do |bool, state|
+            bool ? outer_state.value : state.notice!("#if returned false")
           end
         end
       end
 
+      # Keeps map, only if block is false
+      #
+
+      # @example Keep unless value contains "A"
+      #   map = Remap::Rule::Map.call({}).if_not do
+      #     value.include?("A")
+      #   end
+      #
+      #   error = -> failure { raise failure.exception }
+      #
+      #   a = Remap::State.call("A")
+      #   map.call(a, &error).key?(:value) # => false
+      #
+      #   b = Remap::State.call("BA")
+      #   map.call(b, &error).key?(:value) # => false
+      #
+      #   c = Remap::State.call("C")
+      #   map.call(c, &error).fetch(:value) # => "C"
+      #
+      # @return [Map]
       def if_not(&block)
-        add do |state|
-          state.execute(&block).fmap do |bool, &error|
-            bool ? error["#if_not returned true"] : state.value
+        add do |outer_state|
+          outer_state.execute(&block).fmap do |bool, state|
+            bool ? state.notice!("#if_not returned false") : outer_state.value
           end
         end
       end
 
       private
 
+      # @return [self]
       def add(&block)
         tap { fn << block }
       end
 
+      # @return [Array<Proc>]
       def fn
         @fn ||= []
       end
+
+      # @return [Proc]
+      def callback
+        -> state do
+          fn.reduce(state) do |inner, fn|
+            fn[inner]
+          end
+        end
+      end
+
+      # Catches :fatal and raises {Notice::Error}
+      #
+      # @param state [State]
+      # @param id (:fatal) [:fatal, :notice, :ignore]
+      #
+      # raise [Notice::Error]
+      def fatal(state, id: :fatal, &block)
+        raise catch(id, &block).traced(backtrace).exception
+      end
+
+      # Catches :notice exceptions and repackages them as a state
+      #
+      # @param state [State]
+      #
+      # @return [State]
+      def notice(state, &block)
+        state.set(notice: catch(:notice, &block).traced(backtrace)).except(:value)
+      end
+
+      # @abstract
+      def ignore(...)
+        raise NotImplementedError, "#{self.class}#ignore"
+      end
     end
   end
 end