metaractor 2.1.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 871ec542d6215f116b734516dc46ca8254cfa558576a43bbe58130c32dc043c3
-  data.tar.gz: 35f548db1260d6702ee931c9fa9c9a2bc89b06d318f040839822827dbbd6c928
+  metadata.gz: 67f974131ea1d40f037b6bd29173092b95ab31fbe2263d4274d8dd614ba0483c
+  data.tar.gz: 25bfc2e214f0b8da6fe6964a8426989454ea244d841138b341b1a70f4ec2e5b5
 SHA512:
-  metadata.gz: ee9e4424b4040ce356cfaa092e83c302e57bcac4716d80e4c89ac59551f48f0c97dfc9fa2e159988ca0188adb79087a7f085f21f972853fafc8541066d92e361
-  data.tar.gz: 474a153dec5a43774e46b59adeb64306ac8d7b10359ccbe77cec3fd01f1a1919ce9075fccc2b8dbbcd4ee802faf8d81e152c3bec98fc960285887e9beaa7a7b7
+  metadata.gz: d0fbacb1db9083b9c596f35d9e8eaaabe54fef7c8ede4ac3ad2f92b0b086efec4c55ced03caa0211325344a3242006d6aea0e0b72e96d16aada1b929168f2e7d
+  data.tar.gz: 307a426d305331d9730b6b12eba50ff0703706e53b7b8235e9082e7d5ddf910644263662465462f838c5c79b0c439858dd03daa19afd74e813bd2bc3c05b6d03

data/Gemfile

@@ -2,3 +2,4 @@ source 'https://rubygems.org'
 
 gemspec
 gem 'pry-byebug'
+gem 'awesome_print'

data/README.md

@@ -44,7 +44,7 @@ result.failure?
 # => true
 result.valid?
 # => false
-result.errors
+result.error_messages
 # => ["Required parameters: (user_id or user)"]
 ```
 
@@ -68,20 +68,41 @@ Metaractor supports complex required parameter statements and you can chain thes
 required and: [:token, or: [:recipient_id, :recipient] ]
 ```
 
+You can also mark a parameter as required with the `required` option:
+```ruby
+parameter :user, required: true
+```
+
 ### Optional Parameters
 As optional parameters have no enforcement, they are merely advisory.
 ```ruby
 optional :enable_logging
 ```
 
-### Skipping Blank Parameter Removal
+### Parameter Options
+Metaractor supports arbitrary parameter options. The following are currently built in.
+Note that you can specify a block of `required` or `optional` parameters and then use
+`parameter` or `parameters` to add options to one or more of them.
+
+#### Skipping Blank Parameter Removal
 By default Metaractor removes blank values that are passed in. You may skip this behavior on a per-parameter basis:
 ```ruby
-allow_blank :name
+parameter :name, allow_blank: true
 ```
 
 You may check to see if a parameter exists via `context.has_key?`.
 
+#### Default Values
+You can specify a default value for a parameter:
+```ruby
+optional :role, default: :user
+```
+
+This works with `allow_blank` and can also be anything that responds to `#call`.
+```ruby
+parameter :role, allow_blank: true, default: -> { context.default_role }
+```
+
 ### Custom Validation
 Metaractor supports doing custom validation before any user supplied before_hooks run.
 ```ruby
@@ -161,6 +182,64 @@ result.errors.to_h
 #    }
 ```
 
+### I18n
+As of v3.0.0, metaractor supports i18n along with structured errors.
+```ruby
+module Users
+  class UpdateUser
+    include Metaractor
+
+    optional :is_admin
+    optional :user
+
+    def call
+      fail_with_error!(
+        errors: {
+          base: :invalid_configuration,
+          is_admin: :true_or_false,
+          user: [ title: :blank, username: [:unique, :blank] ]
+        }
+      )
+    end
+  end
+end
+```
+
+Locale:
+```yaml
+en:
+  errors:
+    parameters:
+      invalid_configuration: 'Invalid configuration'
+      blank: '%{parameter} cannot be blank'
+      unique: '%{parameter} must be unique'
+
+      users:
+        is_admin:
+          true_or_false: 'must be true or false'
+      user:
+        username:
+          unique: 'Username has already been taken'
+```
+
+Metaractor will attempt to use the namespace of the code that reported the error.
+You can see that above with the `users` key in the locale.
+
+The i18n integration will walk its way from the most specific message to the least specific one, stopping at the first one it can find.
+We currently expose the following variables for use in the message:
+- `error_key`: the error we added (ex: `blank` or `invalid_configuration`)
+- `parameter`: the name of the parameter
+
+You can also use this feature to work with machine readable keys:
+```ruby
+result = Users::UpdateUser.call
+if result.failure? &&
+  result.errors[:is_admin] == :true_or_false
+
+  # handle this specific case
+end
+```
+
 ### Spec Helpers
 Enable the helpers and/or matchers:
 ```ruby
@@ -221,8 +300,8 @@ expect(result).to include_errors(
 expect(result).to include_errors('user.title cannot be blank')
 ```
 
-### Error Output
-Metaractor customizes the exception message for `Interactor::Failure`:
+### Hash Formatting
+Metaractor customizes the output for `Metaractor::Errors#inspect` and `Interactor::Failure`:
 ```
 Interactor::Failure:
        Errors:
@@ -235,10 +314,12 @@ Interactor::Failure:
        {:parent=>true, :chained=>true}
 ```
 
-You can further customize the exception message:
+You can further customize the hash formatting:
 ```ruby
-# Configure FailureOutput to use awesome_print
-Metaractor::FailureOutput.hash_formatter = ->(hash) { hash.ai }
+Metaractor.configure do |config|
+  # Configure Metaractor to use awesome_print
+  config.hash_formatter = ->(hash) { hash.ai }
+end
 ```
 
 ### Further Reading

data/lib/metaractor/context_errors.rb

@@ -8,29 +8,29 @@ module Metaractor
       super
     end
 
-    def fail_with_error!(message: nil, errors: nil)
-      add_error(message: message, errors: errors)
+    def fail_with_error!(message: nil, errors: nil, **args)
+      add_error(message: message, errors: errors, **args)
       fail!
     end
 
-    def fail_with_errors!(messages: [], errors: {})
-      add_errors(messages: messages, errors: errors)
+    def fail_with_errors!(messages: [], errors: {}, **args)
+      add_errors(messages: messages, errors: errors, **args)
       fail!
     end
 
-    def add_error(message: nil, errors: nil)
+    def add_error(message: nil, errors: nil, **args)
       if message.nil?
-        add_errors(errors: errors)
+        add_errors(errors: errors, **args)
       else
-        add_errors(messages: Array(message))
+        add_errors(messages: Array(message), **args)
       end
     end
 
-    def add_errors(messages: [], errors: {})
+    def add_errors(messages: [], errors: {}, **args)
       if !messages.empty?
-        self.errors.add(errors: { base: messages })
+        self.errors.add(errors: { base: messages }, **args)
       else
-        self.errors.add(errors: errors)
+        self.errors.add(errors: errors, **args)
       end
     end
 

data/lib/metaractor/errors.rb

@@ -4,13 +4,72 @@ module Metaractor
   class Errors
     extend Forwardable
 
+    class Error
+      attr_reader :value, :object
+
+      def initialize(value:, object: nil)
+        @value = value
+        @object = object
+      end
+
+      def generate_message(path_elements:)
+        if @value.is_a? Symbol
+          defaults = []
+
+          if object.class.respond_to?(:i18n_parent_names) &&
+              !object.class.i18n_parent_names.empty?
+
+            names = object.class.i18n_parent_names
+            until names.empty?
+              defaults << ['errors', names.join('.'), 'parameters', path_elements.join('.'), @value.to_s].reject do |item|
+                item.nil? || item == ''
+              end.join('.').to_sym
+              names.pop
+            end
+          end
+
+          unless path_elements.empty?
+            defaults << :"errors.parameters.#{path_elements.join('.')}.#{@value}"
+          end
+          defaults << :"errors.parameters.#{@value}"
+
+          key = defaults.shift
+          I18n.translate(
+            key,
+            default: defaults,
+            error_key: @value,
+            parameter: path_elements.last
+          )
+        else
+          "#{path_elements.join('.')} #{@value}".lstrip
+        end
+      end
+
+      def ==(other)
+        if other.is_a?(self.class)
+          @value == other.value
+        else
+          @value == other
+        end
+      end
+      alias eql? ==
+
+      def hash
+        @value.hash
+      end
+
+      def inspect
+        "(Error) #{@value.inspect}"
+      end
+    end
+
     def initialize
       @tree = Sycamore::Tree.new
     end
 
-    def_delegators :@tree, :to_h, :empty?
+    def_delegators :@tree, :empty?
 
-    def add(error: {}, errors: {})
+    def add(error: {}, errors: {}, object: nil)
       trees = []
       [error, errors].each do |h| 
         tree = nil
@@ -29,7 +88,17 @@ module Metaractor
       end
 
       trees.each do |tree|
-        @tree.add(tree)
+        tree.each_path do |path|
+          node = path.node
+          unless node.is_a?(Error)
+            node = Error.new(
+              value: path.node,
+              object: object
+            )
+          end
+
+          @tree[path.parent] << node
+        end
       end
       @tree.compact
     end
@@ -58,9 +127,9 @@ module Metaractor
       result = @tree.dig(*path)
 
       if result.strict_leaves?
-        result.nodes
+        unwrapped_enum(result.nodes)
       else
-        result.to_h
+        unwrapped_tree(result).to_h
       end
     end
     alias [] dig
@@ -68,9 +137,15 @@ module Metaractor
     def include?(*elements)
       if elements.size == 1 &&
           elements.first.is_a?(Hash)
-        @tree.include?(*elements)
+        unwrapped_tree.include?(*elements)
       else
-        full_messages.include?(*elements)
+        if elements.all? {|e| e.is_a? String }
+          full_messages.include?(*elements)
+        else
+          elements.all? do |element|
+            @tree.include_path?(element)
+          end
+        end
       end
     end
 
@@ -83,7 +158,28 @@ module Metaractor
         end
       end
 
-      new_tree.to_h
+      unwrapped_tree(new_tree).to_h
+    end
+
+    def to_h(unwrap: true)
+      if unwrap
+        unwrapped_tree.to_h
+      else
+        @tree.to_h
+      end
+    end
+
+    def inspect
+      str = "<##{self.class.name}: "
+
+      if !self.empty?
+        str << "Errors:\n"
+        str << Metaractor.format_hash(to_h(unwrap: false))
+        str << "\n"
+      end
+
+      str << ">"
+      str
     end
 
     private
@@ -96,7 +192,32 @@ module Metaractor
         end
       end
 
-      "#{path_elements.join('.')} #{path.node.to_s}".lstrip
+      path.node.generate_message(path_elements: path_elements)
     end
+
+    def unwrapped_tree(orig_tree = @tree)
+      tree = Sycamore::Tree.new
+      orig_tree.each_path do |path|
+        node = path.node
+        if node.is_a? Error
+          node = node.value
+        end
+
+        tree[path.parent] << node
+      end
+
+      tree
+    end
+
+    def unwrapped_enum(orig)
+      orig.map do |element|
+        if element.is_a? Error
+          element.value
+        else
+          element
+        end
+      end
+    end
+
   end
 end

data/lib/metaractor/failure_output.rb

@@ -1,23 +1,11 @@
 module Metaractor
   module FailureOutput
-    def self.format_hash(hash)
-      if @hash_formatter.nil?
-        @hash_formatter = ->(hash){ hash.inspect }
-      end
-
-      @hash_formatter.call(hash)
-    end
-
-    def self.hash_formatter=(callable)
-      @hash_formatter = callable
-    end
-
     def to_s
       str = ''
 
       if !context.errors.empty?
         str << "Errors:\n"
-        str << Metaractor::FailureOutput.format_hash(context.errors.to_h)
+        str << Metaractor.format_hash(context.errors.to_h)
         str << "\n\n"
       end
 
@@ -31,7 +19,7 @@ module Metaractor
       end
 
       str << "Context:\n"
-      str << Metaractor::FailureOutput.format_hash(context.to_h.reject{|k,_| k == :errors})
+      str << Metaractor.format_hash(context.to_h.reject{|k,_| k == :errors})
       str
     end
   end

data/lib/metaractor/handle_errors.rb

@@ -3,20 +3,20 @@ module Metaractor
   class InvalidError < Error; end
 
   module HandleErrors
-    def fail_with_error!(*args)
-      context.fail_with_error!(*args)
+    def fail_with_error!(**args)
+      context.fail_with_error!(object: self, **args)
     end
 
-    def fail_with_errors!(*args)
-      context.fail_with_errors!(*args)
+    def fail_with_errors!(**args)
+      context.fail_with_errors!(object: self, **args)
     end
 
-    def add_error(*args)
-      context.add_error(*args)
+    def add_error(**args)
+      context.add_error(object: self, **args)
     end
 
-    def add_errors(*args)
-      context.add_errors(*args)
+    def add_errors(**args)
+      context.add_errors(object: self, **args)
     end
 
     def error_messages

data/lib/metaractor/namespace.rb

@@ -0,0 +1,46 @@
+module Metaractor
+  module Namespace
+    # The following code is adapted from rails.
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def module_parent_name
+        if defined?(@parent_name)
+          @parent_name
+        else
+          parent_name = name =~ /::[^:]+\z/ ? -$` : nil
+          @parent_name = parent_name unless frozen?
+          parent_name
+        end
+      end
+
+      def module_parent_names
+        parents = []
+        if module_parent_name
+          parents = module_parent_name.split("::")
+        end
+        parents
+      end
+
+      def i18n_parent_names
+        module_parent_names.map {|name| underscore_module_name(name).to_sym }
+      end
+
+      private
+
+      def underscore_module_name(camel_cased_word)
+        return camel_cased_word unless /[A-Z-]|::/.match?(camel_cased_word)
+        word = camel_cased_word.to_s.gsub("::", "/")
+        word.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+        word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+        word.tr!("-", "_")
+        word.downcase!
+        word
+      end
+
+    end
+  end
+end

data/lib/metaractor/parameters.rb

@@ -1,3 +1,5 @@
+# Special thanks to the `hashie` and `active_attr` gems for code and inspiration.
+
 module Metaractor
   module Parameters
     def self.included(base)
@@ -6,40 +8,92 @@ module Metaractor
         include Metaractor::HandleErrors
 
         class << self
-          attr_writer :_required_parameters
-          attr_writer :_optional_parameters
-          attr_writer :_allow_blank
+          attr_writer :requirement_trees
         end
 
         before :remove_blank_values
+        before :apply_defaults
         before :validate_required_parameters
       end
     end
 
+    class Parameter
+      include Comparable
+
+      attr_reader :name
+
+      def initialize(name, **options)
+        @name = name.to_sym
+        @options = options
+      end
+
+      def <=>(other)
+        return nil unless other.instance_of? self.class
+        return nil if name == other.name && options != other.options
+        self.name.to_s <=> other.name.to_s
+      end
+
+      def [](key)
+        @options[key]
+      end
+
+      def dig(name, *names)
+        @options.dig(name, *names)
+      end
+
+      def merge!(**options)
+        @options.merge!(**options)
+      end
+
+      def to_s
+        name.to_s
+      end
+
+      def to_sym
+        name
+      end
+
+      protected
+      attr_reader :options
+    end
+
     module ClassMethods
-      def _required_parameters
-        @_required_parameters ||= []
+      def parameter(name, **options)
+        if param = self.parameter_hash[name.to_sym]
+          param.merge!(**options)
+        else
+          Parameter.new(name, **options).tap do |parameter|
+            self.parameter_hash[parameter.name] = parameter
+          end
+        end
       end
 
-      def required(*params)
-        self._required_parameters += params
+      def parameters(*names, **options)
+        names.each do |name|
+          parameter(name, **options)
+        end
       end
-      alias_method :required_parameters, :required
 
-      def _optional_parameters
-        @_optional_parameters ||= []
+      def parameter_hash
+        @parameters ||= {}
       end
 
-      def optional(*params)
-        self._optional_parameters += params
+      def requirement_trees
+        @requirement_trees ||= []
       end
 
-      def _allow_blank
-        @_allow_blank ||= []
+      def required(*params, **options)
+        if params.empty?
+          tree = options
+          self.requirement_trees << tree
+          parameters(*parameters_in_tree(tree), required: tree)
+        else
+          parameters(*params, required: true, **options)
+        end
       end
 
-      def allow_blank(*params)
-        self._allow_blank += params
+      def optional(*params, **options)
+        parameters(*params, **options)
       end
 
       def validate_parameters(*hooks, &block)
@@ -50,26 +104,74 @@ module Metaractor
       def validate_hooks
         @validate_hooks ||= []
       end
+
+      def parameters_in_tree(tree)
+        if tree.respond_to?(:to_h)
+          tree.to_h.values.first.to_a.flat_map {|t| parameters_in_tree(t)}
+        else
+          [tree]
+        end
+      end
+    end
+
+    def parameters
+      self.class.parameter_hash
+    end
+
+    def requirement_trees
+      self.class.requirement_trees
+    end
+
+    def requirement_trees=(trees)
+      self.class.requirement_trees=(trees)
     end
 
     def remove_blank_values
       to_delete = []
-      context.each_pair do |k,v|
-        next if self.class._allow_blank.include?(k)
+      context.each_pair do |name, value|
+        next if parameters.dig(name, :allow_blank)
 
         # The following regex is borrowed from Rails' String#blank?
-        to_delete << k if (v.is_a?(String) && /\A[[:space:]]*\z/ === v) || v.nil?
+        to_delete << name if (value.is_a?(String) && /\A[[:space:]]*\z/ === value) || value.nil?
       end
-      to_delete.each do |k|
-        context.delete_field k
+
+      to_delete.each do |name|
+        context.delete_field name
+      end
+    end
+
+    def apply_defaults
+      parameters.each do |name, parameter|
+        next unless parameter[:default]
+
+        unless context.has_key?(name)
+          context[name] = _parameter_default(name)
+        end
+      end
+    end
+
+    def _parameter_default(name)
+      default = self.parameters[name][:default]
+
+      case
+      when default.respond_to?(:call) then instance_exec(&default)
+      when default.respond_to?(:dup) then default.dup
+      else default
       end
     end
 
     def validate_required_parameters
       context.errors ||= []
 
-      self.class._required_parameters.each do |param|
-        require_parameter param
+      parameters.each do |name, parameter|
+        next if !parameter[:required] ||
+          parameter[:required].is_a?(Hash)
+
+        require_parameter name
+      end
+
+      requirement_trees.each do |tree|
+        require_parameter tree
       end
 
       run_validate_hooks

data/lib/metaractor/version.rb

@@ -1,3 +1,3 @@
 module Metaractor
-  VERSION = "2.1.1"
+  VERSION = "3.0.0"
 end

data/lib/metaractor.rb

@@ -10,6 +10,8 @@ require 'metaractor/chain_failures'
 require 'metaractor/fail_from_context'
 require 'metaractor/context_has_key'
 require 'metaractor/failure_output'
+require 'i18n'
+require 'metaractor/namespace'
 
 module Metaractor
   def self.included(base)
@@ -43,7 +45,8 @@ module Metaractor
       { module: Metaractor::HandleErrors, method: :include },
       { module: Metaractor::Parameters, method: :include },
       { module: Metaractor::RunWithContext, method: :include },
-      { module: Metaractor::ChainFailures, method: :include }
+      { module: Metaractor::ChainFailures, method: :include },
+      { module: Metaractor::Namespace, method: :include }
     ]
   end
 
@@ -54,4 +57,24 @@ module Metaractor
   def self.prepend_module(mod)
     modules << { module: mod, method: :prepend }
   end
+
+  def self.format_hash(hash)
+    if @hash_formatter.nil?
+      @hash_formatter = default_hash_formatter
+    end
+
+    @hash_formatter.call(hash)
+  end
+
+  def self.default_hash_formatter
+    ->(hash){ hash.inspect }
+  end
+
+  def self.hash_formatter
+    @hash_formatter
+  end
+
+  def self.hash_formatter=(callable)
+    @hash_formatter = callable
+  end
 end

data/metaractor.gemspec

@@ -20,8 +20,11 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency 'interactor', '~> 3.1'
   spec.add_runtime_dependency 'sycamore', '~> 0.3'
+  spec.add_runtime_dependency 'i18n', '~> 1.8'
 
   spec.add_development_dependency 'bundler', '~> 2'
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.9'
+  spec.add_development_dependency 'awesome_print', '~> 1.8'
+  spec.add_development_dependency 'pry-byebug', '~> 3.9'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metaractor
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 3.0.0
 platform: ruby
 authors:
 - Ryan Schlesinger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-04-09 00:00:00.000000000 Z
+date: 2020-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: interactor
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +94,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
 description: 
 email:
 - ryan@outstand.com
@@ -105,6 +147,7 @@ files:
 - lib/metaractor/fail_from_context.rb
 - lib/metaractor/failure_output.rb
 - lib/metaractor/handle_errors.rb
+- lib/metaractor/namespace.rb
 - lib/metaractor/parameters.rb
 - lib/metaractor/run_with_context.rb
 - lib/metaractor/spec.rb