light_service-validated_context 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d272960b5f0002c3b640bba8eeca1684477df3c65a6c7031f3169abcd97eb3f2
-  data.tar.gz: 13f2d1b53652113892ad2d5e93a34aefee19ed38901034e33ac9764590756289
+  metadata.gz: c16c17a54c9867f59ccbf92ec6d969760eb396719ecda969e12d2fec2b063623
+  data.tar.gz: 62103f8748ab7efc04cad3253d5dc5aabd153ae62e4d022ca0427365dc2f657f
 SHA512:
-  metadata.gz: 483f3c71553b51875b1e10d45c113f42ef3d93102658e7df5499bb912fffb810b9555fade2506eaf6e0c1bc4573b06f8b08b179ee1f2d6a336899f8e519d5aad
-  data.tar.gz: c0b8e60f94ad3dbeda5d3e10377633fb6dc248543176fda3d5e4353034e76c8b48804c855d7f9c0d778fe0a7180fa313ae313624fc8a26c1cc4257529cf67ce9
+  metadata.gz: 79c63b97672442aabfdc1215f1ca1e5c92293508da7ab3cea9e23e6453a1b9017f240501af69aa7423780f4b9b77b3ae5eecb53aa4b7d80dbaecb0285b94271e
+  data.tar.gz: 003447c4164440525f526cca2859f3151ebaeb7cc7ba4e32d3ef1f2022b3aa9418ab699400975d4bbe659444678c6df1226716959c00d6c2ccad2a944e547d13

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    light_service-validated_context (0.2.2)
+    light_service-validated_context (0.3.0)
       dry-types (~> 1.7.0)
       light-service (>= 0.18.0)
       zeitwerk

data/README.md

@@ -47,26 +47,57 @@ require 'light_service/validated_context'
 
 ## Usage
 
+The plugin enables you to pass `VK` (`ValidatedKeys`) objects as arguments to built-ins `expects` and
+`promises` macros.
+
+This is how you'd usually write an `Action` in LightService:
+
+```ruby
+class ActionOne
+  extend LightService::Action
+
+  expects :age
+  promises :text
+
+  executed do |context|
+    validate_age!(context)
+
+    # Do something...
+
+    context.text = 'Long live and prosperity'
+  end
+
+  def self.validate_age!(context)
+    context.fail_and_return!(':age must be an Integer') unless context.age.is_a? Integer
+    context.fail_and_return!('Sorry, you are too young m8') if (context.age <= 30)
+  end
+end
+```
+
+and this is how `light_service-validated_context` enables you to write
+
 ```ruby
 class ActionOne
   extend LightService::Action
 
-  expects VK.new(:email, Types::Strict::String)
   expects VK.new(:age, Types::Coercible::Integer.constrained(gt: 30))
-  expects VK.new(:ary, Types::Array.of(Types::Strict::Symbol).constrained(min_size: 1))
-  promises VK.new(:text, Types::Strict::String.constrained(max_size: 10).default('foobar'))
+  promises VK.new(:text, Types::Strict::String.constrained(max_size: 10).default('Long live and prosperity'))
 
   executed do |context|
-    # something happens
+    # Do something
   end
 end
+```
+
+and you'll get validations for free
 
-result = ActionOne.execute(email: 'foo@example.com', age: '37', ary: [:foo])
-# => {:email=>"foo@example.com", :age=>37, :ary=>[:foo], :text=>"foobar"}
-result = ActionOne.execute(age: '37', ary: [:foo])
-# expected :email to be in the context during ActionOne (LightService::ExpectedKeysNotInContextError)
-result = ActionOne.execute(email: 'foo@example.com', age: '37', ary: [])
-# [] violates constraints (min_size?(1, []) failed) (LightService::ExpectedKeysNotInContextError)
+```ruby
+ActionOne.execute(age: '19')
+# [App::ActionOne][:age] "19" violates constraints (gt?(30, 19) failed) (LightService::ExpectedKeysNotInContextError)
+ActionOne.execute(age: 37)
+# LightService::Context({:age=>37, :text=>"Long live and prosperity"}, success: true, message: '', error_code: nil, skip_remaining: false, aliases: {})
+ActionOne.execute(age: 37, text: 'Too long too pass the constrain')
+# [App::ActionOne][:text] "Too long too pass the constrain" violates constraints (max_size?(24, "Too long too pass the constrain") failed) (LightService::PromisedKeysNotInContextError)
 ```
 
 Since all the validation and coercion logic is delegated to `dry-types`, you can
@@ -75,7 +106,7 @@ read more about what you can achieve at https://dry-rb.org/gems/dry-types/1.2/
 `VK` objects needs to be created with 2 positional arguments:
 
 - key name as a symbol
-- A type
+- A type declaration from `dry-types` (`Tyeps` namespace is already setup for you)
 
 `VK` and `ValidatedKey` (equivalent) are short aliases for `LightService::Context::ValidatedKey`.
 They are created only if not already defined in the global space. You're free to use the namespaced
@@ -83,20 +114,53 @@ form to avoid name collisions.
 
 You can find more usage example in `spec/support/test_doubles.rb`
 
+### Custom validation error message
+
+You can set a custom validation error message when instantiating a `VK`
+
+```ruby
+VK.new(:my_integer, Types::Strict::Integer, message: 'Custom validatio message for :my_integer key')
+```
+
+Messages translated via `I18n` are supported too, following stardard `light-service`'s configuration
+
+```ruby
+VK.new(:my_integer, Types::Strict::Integer, message: :my_integer_error_message)
+```
+
+### Raise vs fail
+
+By default, following original `light-service` implementation, a validation error will raise
+and error.
+
+May you prefere to fail the action populating outcome's message with error message:
+
+```ruby
+class ActionFailInsteadOfRaise
+  extend LightService::Action
+  extend LightService::Context::FailOnValidationError
+
+  expects VK.new(:foo, Types::String)
+
+  executed do |context|
+    # do something
+  end
+end
+
+result = ActionFailInsteadOfRaise.execute(foo: 12)
+result.message # Here you'll find the validation(s) message(s)
+```
+
 ## Why validation matters?
 
-In OO programming there's a rule (strict or "of thumb", IDK) that says to "never" instantiate an
-invalid object whenever the object self has the concept of _validity_ for itself. This rule takes
-sense to my eyes whenever I'm working with an object already initialized and in memory, but I cannot
-trust its internal status.
+In OO programming there's a rule (strict or "of thumb", IDK) that says to never instantiate an
+invalid object - given the object itself has the concept of _validity_.
 
-Taken that `light-service` doesn't work on instances, but it works on classes and class methods
-having a more functional and stateless approach, side effects of having invalid state in the context
-(which is The state of an Action/Organizer) are mostly the same.
+How many times do you find yourself working with an object already initialized and in memory, but
+you cannot trust its internal status?
 
-Rewording: if I cannot trust the state, given
-the state is internal or delegated to a context object, I'll have to to a bunch of validation-oriented
-logical branches into my logic. E.g.:
+If you cannot trust the state, given the state is internal or delegated to a context object,
+you'll have to do a bunch of validation-oriented logical branches into your logic. E.g.:
 
 ```ruby
 class HugAFriend
@@ -110,7 +174,7 @@ class HugAFriend
 end
 ```
 
-The `if` in this uber-trivial example exists just due to lack of trust on the state.
+The `if` in this uber-trivial example exists just due to untrusted state.
 
 Let's re-imagine the code given an `executed` block that totally trusts the context:
 
@@ -122,6 +186,7 @@ class HugAFriend
   expects VK.new(:friend, Types.Instance(Friend))
   # Or a less usual approach could be to trust duck typing
   # expects VK.new(:friend, Types::Interface(:hug))
+  # Actually not all friends do appreciate hugs nor other forms of physical contact :P
 
   executed do |context|
     context.friend.hug
@@ -131,6 +196,8 @@ end
 
 ## Comparison with similar gems
 
+A brief comparison about what similar gems offer to work with validation.
+
 This is a comparison table I've done using my own limited experience w/ other solutions
 and/or reading projects' READMEs. Don't take my word for it. And if I was wrong understanding
 some features, feel free to drop me a line on Mastodon [@alessandrofazzi@mastodon.uno](https://mastodon.uno/@alessandrofazzi)
@@ -140,11 +207,11 @@ some features, feel free to drop me a line on Mastodon [@alessandrofazzi@mastodo
 | presence                  | ✅                      | ✅                                                    | ❌                         | ⚠️ Only input, not output   | ✅                                             |
 | static default            | ✅                      | ✅                                                    | ❌                         | ✅                                 | ✅                                             |
 | dynamic default           | ✅                      | ✅                                                    | ❌                         | ✅                                 | ✅                                             |
-| raise or fail control     | ❌                      | ✅                                                    | ❌                         | ❓                                 | ❌                                             |
+| raise or fail control     | ❌                      | ✅                                                    | ❌                         | ❓                                 | ✅                                             |
 | type check                | ❌                      | ✅                                                    | ❌                         | ✅                                 | ✅                                             |
 | data structure type check | ❌                      | ❌                                                    | ❌                         | ❌                                 | ✅                                             |
 | optional                  | ⚠️ through `default`    | ✅ through `allow_nil` (which defaults to `true` 🤔 ❓) | ❌                         | ⚠️ through `default`               | ✅                                             |
-| built-in                  | ✅                      | ✅                                                     | ❌                         | ❌ ActiveModel::Validation        | ❌ Dry::Types                                  |
+| 1st party code                | ✅                      | ✅                                                     | ✅                         | ❌ ActiveModel::Validation        | ❌ Dry::Types                                  |
 
 
 ## Development

data/lib/light_service/validated_context/expected_key_verifier.rb

@@ -18,14 +18,12 @@ module ValidatedContext
       action.expected_keys
     end
 
-    def throw_error_predicate(keys)
+    def throw_error_predicate(_keys)
       type_check_and_coerce_keys!(raw_keys)
 
-      keys_are_all_present = are_all_keys_in_context?(keys)
+      return false if are_all_keys_valid?
 
-      return false if are_all_keys_valid? && keys_are_all_present
-
-      true
+      should_throw_on_validation_error?
     end
   end
 end

data/lib/light_service/validated_context/fail_on_validation_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module ValidatedContext
+  module FailOnValidationError
+    def fail_on_validation_error? = true
+    def throw_on_validation_error? = !fail_on_validation_error?
+  end
+end

data/lib/light_service/validated_context/key_verifier.rb

@@ -2,6 +2,14 @@
 
 module ValidatedContext
   module KeyVerifier
+    def initialize(context, action)
+      @validation_errors = []
+
+      super(context, action)
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    # Refactoring this is out of my scope ATM
     def type_check_and_coerce_keys!(keys)
       errors = []
 
@@ -11,12 +19,16 @@ module ValidatedContext
         begin
           context[key.label] = key.type[context[key.label] || Dry::Types::Undefined]
         rescue Dry::Types::CoercionError => e
-          errors << "[#{action}][:#{key.label}] #{e.message}"
+          errors << (
+            LightService::Configuration.localization_adapter.failure(key.message, action) ||
+              "[#{action}][:#{key.label}] #{e.message}"
+          )
         end
       end
-      # debugger
+
       @validation_errors = errors
     end
+    # rubocop:enable Metrics/AbcSize
 
     def are_all_keys_valid?
       @validation_errors.none?
@@ -25,5 +37,12 @@ module ValidatedContext
     def error_message
       @validation_errors.join(', ')
     end
+
+    def should_throw_on_validation_error?
+      return true unless action.respond_to?(:fail_on_validation_error?) && action.fail_on_validation_error?
+
+      context.fail!(error_message)
+      false
+    end
   end
 end

data/lib/light_service/validated_context/promised_key_verifier.rb

@@ -18,14 +18,12 @@ module ValidatedContext
       action.promised_keys
     end
 
-    def throw_error_predicate(keys)
+    def throw_error_predicate(_keys)
       type_check_and_coerce_keys!(raw_keys)
 
-      keys_are_all_present = are_all_keys_in_context?(keys)
+      return false if are_all_keys_valid?
 
-      return false if are_all_keys_valid? && keys_are_all_present
-
-      true
+      should_throw_on_validation_error?
     end
   end
 end

data/lib/light_service/validated_context/validated_key.rb

@@ -1,7 +1,15 @@
 # frozen_string_literal: true
 
 module ValidatedContext
-  ValidatedKey = Struct.new(:label, :type) do
+  class ValidatedKey
+    attr_reader :label, :type, :message
+
+    def initialize(label, type, message: nil)
+      @label = label
+      @type = type
+      @message = message
+    end
+
     def to_sym
       label.to_sym
     end

data/lib/light_service/validated_context/version.rb

@@ -2,6 +2,6 @@
 
 module LightService
   module ValidatedContext
-    VERSION = "0.2.2"
+    VERSION = "0.3.0"
   end
 end

data/lib/light_service/validated_context.rb

@@ -12,6 +12,7 @@ module ValidatedContext; end
 module LightService
   class Context
     ValidatedKey = ::ValidatedContext::ValidatedKey
+    FailOnValidationError = ::ValidatedContext::FailOnValidationError
     prepend ::ValidatedContext::Context
 
     class KeyVerifier

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: light_service-validated_context
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - "'Alessandro Fazzi'"
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-30 00:00:00.000000000 Z
+date: 2022-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-types
@@ -69,6 +69,7 @@ files:
 - lib/light_service/validated_context.rb
 - lib/light_service/validated_context/context.rb
 - lib/light_service/validated_context/expected_key_verifier.rb
+- lib/light_service/validated_context/fail_on_validation_error.rb
 - lib/light_service/validated_context/key_verifier.rb
 - lib/light_service/validated_context/promised_key_verifier.rb
 - lib/light_service/validated_context/validated_key.rb