remap 2.0.3 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: feae800c3a05859a5cf0cefd1c080f3afa92109856b504aba89f81975f21dfc4
-  data.tar.gz: 54c5b5b7dd28b67b67aed40019867d6293141edca668ea8d4de9b5b670dedaa4
+  metadata.gz: b3b3344d7c0ab3825ba1bb0a80c5ddbd7a00d57dbf762b0e26cd3cc6216e0644
+  data.tar.gz: 30db4e775e16a7923c46d4f1ca41b0b207ab0bb21cf791179a8fd76cbad9d455
 SHA512:
-  metadata.gz: ecabf17439228869a9e14a2686cc38d92cd495a529efa2fc6114ffb10abf40837fe3fccf858123134f10c6a54f314e2464d8d309f854183b69c2875733cd48f4
-  data.tar.gz: cc27691d7b1710d9642368559a25b7da4009c5a4346b5b44aa6166b81a8ec3ea053276ebd20b5d976548bf65290e9d2b4395395c2932edaaea8cea08bbdd285f
+  metadata.gz: e590c6d048e6cbb822c6bc49428f05e0dd6ead0f0f8752d563b5660adf422e61f1f8e2dc899490fedbdeb34bb36e3dc047906b7fe7eacf9a2711021c6f4a1d5f
+  data.tar.gz: 58ebb654582cbcfbfc776fb90a8ff2ce88a840642f1c1669c755478cb582f254f7f41a844762f7a228ed8a812e320aab073836dba190a15a3f0a42406a8740a0

data/lib/remap/base.rb

@@ -1,146 +1,300 @@
 # frozen_string_literal: true
 
-require "dry/monads/all"
+require "active_support/configurable"
+require "active_support/core_ext/object/with_options"
 
 module Remap
+  # @example Select all elements
+  #   class Mapper < Remap::Base
+  #     define do
+  #       map [all, :name]
+  #     end
+  #   end
+  #
+  #   Mapper.call([{ name: "John" }, { name: "Jane" }]) # => ["John", "Jane"]
+  #
+  # @example Given an option
+  #   class Mapper < Remap::Base
+  #     option :name
+  #
+  #     define do
+  #       set [:person, :name], to: option(:name)
+  #     end
+  #   end
+  #
+  #   Mapper.call({}, name: "John") # => { person: { name: "John" } }
+  #
+  # @example Given a value
+  #   class Mapper < Remap::Base
+  #     define do
+  #       set [:api_key], to: value("ABC-123")
+  #     end
+  #   end
+  #
+  #   Mapper.call({}) # => { api_key: "ABC-123" }
+  #
+  # @example Maps ["A", "B", "C"] to ["A", "C"]
+  #   class Mapper < Remap::Base
+  #     define do
+  #       each do
+  #         map.if_not do
+  #           value.include?("B")
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  #   Mapper.call(["A", "B", "C"]) # => ["A", "C"]
+  #
+  # @example Maps ["A", "B", "C"] to ["B"]
+  #   class Mapper < Remap::Base
+  #     define do
+  #       each do
+  #         map.if do
+  #           value.include?("B")
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  #   Mapper.call(["A", "B", "C"]) # => ["B"]
+  #
+  # @example Maps { a: { b: "A" } } to "A"
+  #   class Mapper < Remap::Base
+  #     define do
+  #       map(:a, :b).enum do
+  #         value "A", "B"
+  #       end
+  #     end
+  #   end
+  #
+  #   Mapper.call({ a: { b: "A" } }) # => "A"
+  #   Mapper.call({ a: { b: "B" } }) # => "B"
+  #
+  # @example Map { people: [{ name: "John" }] } to { names: ["John"] }
+  #   class Mapper < Remap::Base
+  #     define do
+  #       map :people, to: :names do
+  #         each do
+  #           map :name
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  #   Mapper.call({ people: [{ name: "John" }] }) # => { names: ["John"] }
+  #
+  # @example Map "Hello" to "Hello!"
+  #   class Mapper < Remap::Base
+  #     define do
+  #       map.adjust do
+  #         "#{value}!"
+  #       end
+  #     end
+  #   end
+  #
+  #   Mapper.call("Hello") # => "Hello!"
+  #
+  # @example Select the second element from an array
+  #   class Mapper < Remap::Base
+  #     define do
+  #       map [at(1)]
+  #     end
+  #   end
+  #
+  #   Mapper.call([1, 2, 3]) # => 2
   class Base < Mapper
-    include Dry::Core::Memoizable
+    include ActiveSupport::Configurable
     include Dry::Core::Constants
-    extend Dry::Monads[:result]
-
-    extend Dry::Configurable
-    extend Forwardable
-
     using State::Extension
-    extend State
+    extend Operation
 
-    CONTRACT = Dry::Schema.JSON do
-      # NOP
+    with_options instance_accessor: true do |scope|
+      scope.config_accessor(:contract) { Dry::Schema.JSON {} }
+      scope.config_accessor(:constructor) { IDENTITY }
+      scope.config_accessor(:options) { EMPTY_ARRAY }
+      scope.config_accessor(:option) { EMPTY_HASH }
+      scope.config_accessor(:rules) { EMPTY_ARRAY }
+      scope.config_accessor(:context) { IDENTITY }
     end
 
-    setting :constructor, default: IDENTITY
-    setting :options, default: EMPTY_ARRAY
-    setting :rules, default: EMPTY_ARRAY
-    setting :contract, default: CONTRACT
-    setting :context, default: IDENTITY
-
-    delegate [:config] => self
-
     schema schema.strict(false)
 
-    # Holds the current context
-    # @private
+    # Defines a schema for the mapper
+    # If the schema fail, the mapper will fail
+    #
+    # @example Guard against missing values
+    #   class MapperWithAge < Remap::Base
+    #     contract do
+    #       required(:age).filled(:integer)
+    #     end
+    #
+    #     define do
+    #       map :age, to: [:person, :age]
+    #     end
+    #   end
+    #
+    #   MapperWithAge.call({age: 50}) # => { person: { age: 50 } }
+    #   MapperWithAge.call({age: '10'}) do |failure|
+    #     # ...
+    #   end
+    #
+    # @see https://dry-rb.org/gems/dry-schema/1.5/
+    #
+    # @return [void]
     def self.contract(&context)
-      config.contract = Dry::Schema.JSON(&context)
+      self.contract = Dry::Schema.JSON(&context)
     end
 
-    # @see Dry::Validation::Contract.rule
+    # Defines a rule for the mapper
+    # If the rule fail, the mapper will fail
+    #
+    # @example Guard against values
+    #   class MapperWithRule < Remap::Base
+    #     contract do
+    #       required(:age)
+    #     end
+    #
+    #     rule(:age) do
+    #       unless value >= 18
+    #         key.failure("must be at least 18 years old")
+    #       end
+    #     end
+    #
+    #     define do
+    #       map :age, to: [:person, :age]
+    #     end
+    #   end
+    #
+    #   MapperWithRule.call({age: 50}) # => { person: { age: 50 } }
+    #   MapperWithRule.call({age: 10}) do |failure|
+    #     # ...
+    #   end
+    #
+    # @see https://dry-rb.org/gems/dry-validation/1.6/rules/
+    #
+    # @return [void]
     def self.rule(...)
-      config.rules << ->(*) { rule(...) }
+      self.rules = rules + [-> * { rule(...) }]
     end
 
-    # Defines a a constructor argument for the mapper
+    # Defines a required option for the mapper
+    #
+    # @example A mapper that takes an argument name
+    #   class MapperWithOption < Remap::Base
+    #     option :name
+    #
+    #     define do
+    #       set :name, to: option(:name)
+    #     end
+    #   end
     #
-    # @param name [Symbol]
-    # @param type [#call]
+    #   MapperWithOption.call({}, name: "John") # => { name: "John" }
+    #
+    # @param field [Symbol]
+    # @option type (Types::Any) [#call]
+    #
+    # @return [void]
     def self.option(field, type: Types::Any)
       attribute(field, type)
 
       unless (key = schema.keys.find { _1.name == field })
-        raise ArgumentError, "Could not locate [#{field}] in [#{self}]"
+        raise ArgumentError, "[BUG] Could not locate [#{field}] in [#{self}]"
       end
 
-      config.options << ->(*) { option(field, type: key) }
+      self.options = options + [-> * { option(field, type: key) }]
     end
 
-    # Pretty print the mapper
+    # Defines a mapper rules and possible constructor
     #
-    # @return [String]
-    def self.inspect
-      "<#{self.class} #{rule}, #{self}>"
-    end
-
-    # Defines a mapper with a constructor used to wrap the output
+    # @param target (Nothing) [#call]
     #
-    # @param constructor [#call]
+    # @option method (:new) [Symbol]
+    # @option strategy (:argument) [:argument, :keywords, :none]
     #
-    # @example A mapper from path :a to path :b
-    #   class Mapper < Remap
+    # @example A mapper, which mapps a value at [:a] to [:b]
+    #   class Mapper < Remap::Base
     #     define do
     #       map :a, to: :b
     #     end
     #   end
     #
-    #   Mapper.call(a: 1) # => { b: 1 }
+    #   Mapper.call({a: 1}) # => { b: 1 }
+    #
+    # @example A mapper with an output constructor
+    #   class Person < Dry::Struct
+    #     attribute :first_name, Dry::Types['strict.string']
+    #   end
+    #
+    #   class Mapper < Remap::Base
+    #     define(Person) do
+    #       map :name, to: :first_name
+    #     end
+    #   end
+    #
+    #   Mapper.call({name: "John"}).first_name # => "John"
+    #
+    # @return [void]
     def self.define(target = Nothing, method: :new, strategy: :argument, &context)
       unless context
         raise ArgumentError, "Missing block"
       end
 
-      config.context = Compiler.call(&context)
-      config.constructor = Constructor.call(method: method, strategy: strategy, target: target)
+      self.context = Compiler.call(&context)
+      self.constructor = Constructor.call(method: method, strategy: strategy, target: target)
     rescue Dry::Struct::Error => e
       raise ArgumentError, e.message
     end
 
-    # Creates a new mapper
+    # Similar to {::call}, but takes a state
     #
-    # @param input [Any]
-    # @param params [Hash]
-
-    # @return [Context]
-
-    extend Operation
-
+    # @param state [State]
+    #
+    # @yield [Failure] if mapper fails
+    #
+    # @return [Result] if mapper succeeds
+    #
+    # @private
     def self.call!(state, &error)
       new(state.options).call(state._.set(mapper: self), &error)
-    rescue Dry::Struct::Error => e
-      raise ArgumentError, "Option missing to mapper [#{self}]: #{e}"
     end
 
-    # Creates a mapper tree using {#context} and uses {#state} as argument
+    # Mappers state according to the mapper rules
     #
-    # @return [State]
+    # @param state [State]
     #
-    # @see .call!
+    # @yield [Failure] if mapper fails
+    #
+    # @return [State]
     #
     # @private
     def call(state, &error)
       unless error
-        raise ArgumentError, "Missing block"
+        raise ArgumentError, "Base#call(state, &error) requires block"
       end
 
       state.tap do |input|
-        contract.call(input, state.options).tap do |result|
+        validation.call(input, state.options).tap do |result|
           unless result.success?
             return error[state.failure(result.errors.to_h)]
           end
         end
       end
 
-      state.then(&config.context).then(&config.constructor)
+      notice = catch :fatal do
+        return context.call(state) do |failure|
+          return error[failure]
+        end.then(&constructor)
+      end
+
+      error[state.failure(notice)]
     end
 
     private
 
-    def contract(scope: self)
-      Class.new(Dry::Validation::Contract) do |klass|
-        config = scope.class.config
-
-        config.rules.each do |rule|
-          klass.class_eval(&rule)
-        end
-
-        config.options.each do |option|
-          klass.class_eval(&option)
-        end
-
-        schema(config.contract)
-      end.new(**attributes)
-    end
-
-    def config
-      self.class.config
+    # @return [Contract]
+    def validation
+      Contract.call(attributes: attributes, contract: contract, options: options, rules: rules)
     end
   end
 end

data/lib/remap/compiler.rb

@@ -1,17 +1,30 @@
 # frozen_string_literal: true
 
 module Remap
-  class Compiler
-    include Dry::Core::Constants
-    extend Dry::Initializer
-    extend Forwardable
-
-    param :rules, default: -> { EMPTY_ARRAY.dup }
+  # Constructs a {Rule} from the block passed to {Remap::Base.define}
+  class Compiler < Proxy
+    # @return [Array<Rule>]
+    param :rules, type: Types.Array(Rule)
 
     # @return [Rule]
-    delegate call: self
+    delegate :call, to: Compiler
 
-    # Constructs a rule tree given {block}
+    # Constructs a rule tree given block
+    #
+    # @example Compiles two rules
+    #   rule = Remap::Compiler.call do
+    #     get :name
+    #     get :age
+    #   end
+    #
+    #   state = Remap::State.call({
+    #     name: "John",
+    #     age: 50
+    #   })
+    #
+    #   error = -> failure { raise failure.exception }
+    #
+    #   rule.call(state, &error).fetch(:value) # => { name: "John", age: 50 }
     #
     # @return [Rule]
     def self.call(&block)
@@ -19,57 +32,109 @@ module Remap
         return Rule::Void.new
       end
 
-      new.tap { _1.instance_eval(&block) }.rule
+      new([]).tap do |compiler|
+        compiler.instance_exec(&block)
+      end.rule
     end
 
-    # Maps {path} to {to} with {block} inbetween
+    # Maps input path [input] to output path [to]
     #
     # @param path ([]) [Array<Segment>, Segment]
     # @param to ([]) [Array<Symbol>, Symbol]
     #
-    # @return [Rule::Map]
-    def map(*path, to: EMPTY_ARRAY, &block)
-      add Rule::Map.new(
+    # @return [Rule::Map::Required]
+    def map(*path, to: EMPTY_ARRAY, backtrace: Kernel.caller, &block)
+      add Rule::Map::Required.call(
         path: {
-          map: path.flatten,
-          to: [to].flatten
+          output: [to].flatten,
+          input: path.flatten
         },
-        rule: call(&block)
-      )
+        backtrace: backtrace,
+        rule: call(&block))
+    end
+
+    # Optional version of {#map}
+    #
+    # @see #map
+    #
+    # @return [Rule::Map::Optional]
+    def map?(*path, to: EMPTY_ARRAY, backtrace: Kernel.caller, &block)
+      add Rule::Map::Optional.call(
+        path: {
+          output: [to].flatten,
+          input: path.flatten
+        },
+        backtrace: backtrace,
+        rule: call(&block))
+    end
+
+    # Select a path and uses the same path as output
+    #
+    # @param path ([]) [Array<Segment>, Segment]
+    #
+    # @return [Rule::Map::Required]
+    def get(*path, backtrace: Kernel.caller, &block)
+      map(path, to: path, backtrace: backtrace, &block)
+    end
+
+    # Optional version of {#get}
+    #
+    # @see #get
+    #
+    # @return [Rule::Map::Optional]
+    def get?(*path, backtrace: Kernel.caller, &block)
+      map?(path, to: path, backtrace: backtrace, &block)
     end
 
-    # Maps using {mapper}
+    # Maps using mapper
     #
     # @param mapper [Remap]
     #
     # @return [Rule::Embed]
-    def embed(mapper)
+    def embed(mapper, &block)
+      if block
+        raise ArgumentError, "#embed does not take a block"
+      end
+
       add Rule::Embed.new(mapper: mapper)
     rescue Dry::Struct::Error
       raise ArgumentError, "Embeded mapper must be [Remap::Mapper], got [#{mapper}]"
     end
 
-    # @param *path ([]) [Symbol, Array<Symbol>]
+    # @param path ([]) [Symbol, Array<Symbol>]
     # @option to [Remap::Static]
     #
     # @return [Rule::Set]
     # @raise [ArgumentError]
     #   if no path given
     #   if path is not a Symbol or Array<Symbol>
-    def set(*path, to:)
-      add Rule::Set.new(path: { to: path.flatten, map: EMPTY_ARRAY }, value: to)
+    def set(*path, to:, &block)
+      if block
+        raise ArgumentError, "#set does not take a block"
+      end
+
+      add Rule::Set.new(path: path.flatten, value: to)
     rescue Dry::Struct::Error => e
       raise ArgumentError, e.message
     end
 
-    # Maps to {path} from {map} with {block} inbetween
+    # Maps to path from map with block in between
     #
     # @param path [Array<Symbol>, Symbol]
     # @param map [Array<Segment>, Segment]
     #
     # @return [Rule::Map]
-    def to(*path, map: EMPTY_ARRAY, &block)
-      map(*map, to: path, &block)
+    def to(*path, map: EMPTY_ARRAY, backtrace: Kernel.caller, &block)
+      map(*map, to: path, backtrace: backtrace, &block)
+    end
+
+    # Optional version of {#to}
+    #
+    # @see #to
+    #
+    # @return [Rule::Map::Optional]
+    def to?(*path, map: EMPTY_ARRAY, &block)
+      map?(*map, to: path, &block)
     end
 
     # Iterates over the input value, passes each value
@@ -79,13 +144,13 @@ module Remap
     # @raise [ArgumentError] if no block given
     def each(&block)
       unless block
-        raise ArgumentError, "no block given"
+        raise ArgumentError, "#each requires a block"
       end
 
       add Rule::Each.new(rule: call(&block))
     end
 
-    # Wraps output in {type}
+    # Wraps output in type
     #
     # @param type [:array]
     #
@@ -95,7 +160,7 @@ module Remap
     # @raise [ArgumentError] if type is not :array
     def wrap(type, &block)
       unless block
-        raise ArgumentError, "no block given"
+        raise ArgumentError, "#wrap requires a block"
       end
 
       add Rule::Wrap.new(type: type, rule: call(&block))
@@ -106,7 +171,11 @@ module Remap
     # Selects all elements
     #
     # @return [Rule::Path::Segment::Quantifier::All]
-    def all
+    def all(&block)
+      if block
+        raise ArgumentError, "all selector does not take a block"
+      end
+
       Selector::All.new(EMPTY_HASH)
     end
 
@@ -115,7 +184,11 @@ module Remap
     # @param value [Any]
     #
     # @return [Rule::Static::Fixed]
-    def value(value)
+    def value(value, &block)
+      if block
+        raise ArgumentError, "option selector does not take a block"
+      end
+
       Static::Fixed.new(value: value)
     end
 
@@ -124,26 +197,39 @@ module Remap
     # @param id [Symbol]
     #
     # @return [Rule::Static::Option]
-    def option(id)
-      Static::Option.new(name: id)
+    def option(id, backtrace: Kernel.caller, &block)
+      if block
+        raise ArgumentError, "option selector does not take a block"
+      end
+
+      Static::Option.new(name: id, backtrace: backtrace)
     end
 
-    # Selects {index} element in input
+    # Selects index element in input
     #
     # @param index [Integer]
     #
     # @return [Path::Segment::Key]
     # @raise [ArgumentError] if index is not an Integer
-    def at(index)
+    def at(index, &block)
+      if block
+        raise ArgumentError, "first selector does not take a block"
+      end
+
       Selector::Index.new(index: index)
     rescue Dry::Struct::Error
-      raise ArgumentError, "Selector at(index) requires an integer argument, got [#{index}] (#{index.class})"
+      raise ArgumentError,
+            "Selector at(index) requires an integer argument, got [#{index}] (#{index.class})"
     end
 
     # Selects first element in input
     #
     # @return [Path::Segment::Key]]
-    def first
+    def first(&block)
+      if block
+        raise ArgumentError, "first selector does not take a block"
+      end
+
       at(0)
     end
     alias any first
@@ -151,7 +237,11 @@ module Remap
     # Selects last element in input
     #
     # @return [Path::Segment::Key]
-    def last
+    def last(&block)
+      if block
+        raise ArgumentError, "last selector does not take a block"
+      end
+
       at(-1)
     end