metaractor 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43fa8164083ceda9dca36dc6584da4bf3ac511e67d0f7a2232468ae841f8bd56
-  data.tar.gz: 1ed5b56c2524f9f73048a8f9f79c2ab4515bafe0749a60122b92841224b5194c
+  metadata.gz: 6e1ab1a1cd9e5ab11a43462021e80787506646d87cf41816ce67396a3cf5da9d
+  data.tar.gz: e9b61e4f8181d10ae02d2b84f712f30eb9a36e457d1dac7dff6a43c802b93785
 SHA512:
-  metadata.gz: 535d587dde182fd7c298f050eefb6a560a35f27ffba8e90afd117a0395f760374b88794c09e2cd84821ba760b26ee0322bd1fd95d8d9b0b2c22dceac8b7cac14
-  data.tar.gz: 8571061ff4a4fcd37d3592a82273db4bf308f394b92bb7f36b2241fbbb07cbca4c2e1b05882af339c4a99891efc0688e23d4f7643e12842e200e18379ac78ec4
+  metadata.gz: eb29390b6649c80867a4455e642cd75bc1fbc6732b583e4441f5fc0a42b3dee14ede6ceaad933322073e3f0dcc328e936e2d9c3f120ea97e75e38acb01cbe1d8
+  data.tar.gz: faa366cc5ad09fed640918a295696e3089a9ef96de61ce3cb073c0a6ee029be58c73db16bc056f781f9b795c776149437c7cfddc0bd84d2182d7ca5da3dabb96

data/README.md

@@ -104,6 +104,143 @@ before do
 end
 ```
 
+### Structured Errors
+As of v2.0.0, metaractor supports structured errors.
+```ruby
+class UpdateUser
+  include Metaractor
+
+  optional :is_admin
+  optional :user
+
+  def call
+    fail_with_error!(
+      errors: {
+        base: 'Invalid configuration',
+        is_admin: 'must be true or false',
+        user: [ title: 'cannot be blank', username: ['must be unique', 'must not be blank'] ]
+      }
+    )
+  end
+end
+
+result = UpdateUser.call
+result.error_messages
+# => [
+#      'Invalid configuration',
+#      'is_admin must be true or false',
+#      'user.title cannot be blank',
+#      'user.username must be unique',
+#      'user.username must not be blank'
+#    ]
+
+result.errors.full_messages_for(:user)
+# => [
+#      'title cannot be blank',
+#      'username must be unique',
+#      'username must not be blank'
+#    ]
+
+# The arguments to `slice` are a list of paths.
+# In this case we're asking for the errors under `base` and also
+# the errors found under user _and_ title.
+result.errors.slice(:base, [:user, :title])
+# => {
+#      base: 'Invalid configuration',
+#      user: { title: 'cannot be blank' }
+#    }
+
+result.errors.to_h
+# => {
+#      base: 'Invalid configuration',
+#      is_admin: 'must be true or false',
+#      user: {
+#        title: 'cannot be blank',
+#        username: ['must be unique', 'must not be blank']
+#      }
+#    }
+```
+
+### Spec Helpers
+Enable the helpers and/or matchers:
+```ruby
+RSpec.configure do |config|
+  config.include Metaractor::Spec::Helpers
+  config.include Metaractor::Spec::Matchers
+end
+```
+
+#### Helpers
+- `context_creator`
+```ruby
+# context_creator(error_message: nil, error_messages: [], errors: [], valid: nil, invalid: nil, success: nil, failure: nil, **attributes)
+
+# Create a blank context:
+context_creator
+
+# Create a context with some data:
+context_creator(message: message, user: user)
+
+# Create an invalid context:
+context_creator(error_message: "invalid context", invalid: true)
+
+# Create a context with string errors:
+context_creator(error_messages: ["That didn't work", "Neither did this"])
+
+# Create a context with structured errors:
+context_creator(
+  user: user,
+  errors: {
+    user: {
+      email: 'must be unique'
+    },
+    profile: {
+      first_name: 'cannot be blank'
+    }
+  }
+)
+```
+
+#### Matchers
+- `include_errors`
+```ruby
+result = context_creator(
+  errors: {
+    user: [
+      title: 'cannot be blank',
+      username: ['must be unique', 'must not be blank']
+    ]
+  }
+)
+
+expect(result).to include_errors(
+  'username must be unique',
+  'username must not be blank'
+).at_path(:user, :username)
+
+expect(result).to include_errors('user.title cannot be blank')
+```
+
+### Error Output
+Metaractor customizes the exception message for `Interactor::Failure`:
+```
+Interactor::Failure:
+       Errors:
+       {:base=>"NOPE"}
+
+       Previously Called:
+       Chained
+
+       Context:
+       {:parent=>true, :chained=>true}
+```
+
+You can further customize the exception message:
+```ruby
+# Configure FailureOutput to use awesome_print
+Metaractor::FailureOutput.hash_formatter = ->(hash) { hash.ai }
+```
+
 ### Further Reading
 For more examples of all of the above approaches, please see the specs.
 

data/lib/metaractor/failure_output.rb

@@ -0,0 +1,39 @@
+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 << "\n\n"
+      end
+
+      if !context._called.empty?
+        str << "Previously Called:\n"
+        context._called.each do |interactor|
+          str << interactor.class.name.to_s
+        end
+        str << "\n\n"
+      end
+
+      str << "Context:\n"
+      str << Metaractor::FailureOutput.format_hash(context.to_h.reject{|k,_| k == :errors})
+      str
+    end
+  end
+end
+
+Interactor::Failure.send(:include, Metaractor::FailureOutput)

data/lib/metaractor/version.rb

@@ -1,3 +1,3 @@
 module Metaractor
-  VERSION = "2.0.0"
+  VERSION = "2.1.0"
 end

data/lib/metaractor.rb

@@ -9,6 +9,7 @@ require 'metaractor/context_validity'
 require 'metaractor/chain_failures'
 require 'metaractor/fail_from_context'
 require 'metaractor/context_has_key'
+require 'metaractor/failure_output'
 
 module Metaractor
   def self.included(base)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metaractor
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Ryan Schlesinger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-03-17 00:00:00.000000000 Z
+date: 2020-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: interactor
@@ -103,6 +103,7 @@ files:
 - lib/metaractor/context_validity.rb
 - lib/metaractor/errors.rb
 - lib/metaractor/fail_from_context.rb
+- lib/metaractor/failure_output.rb
 - lib/metaractor/handle_errors.rb
 - lib/metaractor/parameters.rb
 - lib/metaractor/run_with_context.rb