light_service-validated_context 0.2.2 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d272960b5f0002c3b640bba8eeca1684477df3c65a6c7031f3169abcd97eb3f2
-  data.tar.gz: 13f2d1b53652113892ad2d5e93a34aefee19ed38901034e33ac9764590756289
+  metadata.gz: 859cf8786c692bedc1d764b0656629bc7f9e0ddb741a10874d290c723b708e3d
+  data.tar.gz: 18059f28fcbaaa2d54373bdf2cea6c6f8387fc68b07f83f338631e445ba29e5f
 SHA512:
-  metadata.gz: 483f3c71553b51875b1e10d45c113f42ef3d93102658e7df5499bb912fffb810b9555fade2506eaf6e0c1bc4573b06f8b08b179ee1f2d6a336899f8e519d5aad
-  data.tar.gz: c0b8e60f94ad3dbeda5d3e10377633fb6dc248543176fda3d5e4353034e76c8b48804c855d7f9c0d778fe0a7180fa313ae313624fc8a26c1cc4257529cf67ce9
+  metadata.gz: 7d7a6568947199bf4e96296d03825a65b7485227083d02b72b450598db273e72bae5547b19dd9d32d5ca9a85e9b5e676cc5af4f257f974ec4d4d9e59a8c3ed7f
+  data.tar.gz: eb44c15324105179fb1426fc201d2f34d8bb92e5ccc5e1ed2a265e8c8d85eaf66625b287717c6ec452a8789afa240b69b395fa3050c0a1661ed2026a0fb6e5d0

data/Gemfile.lock

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

data/README.md

@@ -23,7 +23,7 @@ AFAIK this is the only way to achieve the goal. Because of this fact I consider
 ## Goals
 
 - implement an advanced and flexible interface to declare,
-type-check, coerce and describe action's arguments without reinventing the wheel (the wheel we use under the wood is [`dry-types`](https://dry-rb.org/gems/dry-types))
+type-check, coerce and describe action's arguments without reinventing the wheel (the wheel we use under the wood is [`dry-types`](https://dry-rb.org/gems/dry-types/main/custom-types/))
 - testing DX and interfaces
 - study what parts of code are involved into this area of `light-service`'s code base
 
@@ -47,35 +47,66 @@ 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
+```
 
-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)
+and you'll get validations for free
+
+```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
-read more about what you can achieve at https://dry-rb.org/gems/dry-types/1.2/
+read more about what you can achieve at https://dry-rb.org/gems/dry-types/main/custom-types/
 
 `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,91 @@ form to avoid name collisions.
 
 You can find more usage example in `spec/support/test_doubles.rb`
 
-## Why validation matters?
+### Custom validation error message
 
-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.
+You can set a custom validation error message when instantiating a `VK` object
 
-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.
+```ruby
+VK.new(:my_integer, Types::Strict::Integer, message: 'Custom validation message for :my_integer key')
+```
 
-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.:
+Messages translated via `I18n` are supported too, following standard `light-service`'s
+[configuration](https://github.com/adomokos/light-service/#localizing-messages)
+
+```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 a
+`LightService::ExpectedKeysNotInContextError` or `LightService::PromisedKeysNotInContextError`.
+
+> NOTE: I know that raised exceptions do not express the concept of "invalid", but I opted
+to preserve the original one in order to make this plugin more droppable-in as possible, thus
+w/o breaking code relying on, for example, rescueing those specific excpetions.
+
+May you prefere to fail the action, populating outcome's message with error message, just do
+`extend LightService::Context::FailOnValidationError` into you action:
+
+```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)
+```
+
+### Custom types
+
+As documented in [dry-types doc](https://dry-rb.org/gems/dry-types/main/getting-started/#creating-your-first-type),
+you can be more expressive defining custom types; you can define them reopening the already defined `LightService::Types` module
+(or simply `Types` in the global namespace if it does not conflict with your domain's namespace), e.g.:
+
+```ruby
+module LightService::Types
+  MyExpressiveThing = Hash.schema(
+    name: String,
+    age: Coercible::Integer,
+    foo: Symbol.constrained(included_in: %i[bar baz])
+  )
+end
+
+class ActionOne
+  extend LightService::Action
+  extend LightService::Context::FailOnValidationError
+
+  expects VK.new(:foo, Types::MyBusinessHash)
+
+  executed do |context|
+    # do something...
+  end
+end
+
+result = App::ActionOne.execute(foo: {
+  name: 'Alessandro',
+  age: '37',
+  foo: :bar
+})
+```
+
+Custom types will be reusable, more expressive and moreover will clean your action up a bit.
+
+## Why validation matters?
+
+In OO programming there's a rule that says to never instantiate an
+invalid object.
+
+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 +212,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 +224,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 +234,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,12 +245,15 @@ 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                                  |
 
+> NOTE: in `active_interaction` the fact that validation code isn't first party isn't an issue, since
+> the gem is a Rails-only gem and validation is delegated to Rails, thus no additional dependencies
+> are required. `light_service-validated_context` depends on additional gems from the dry-rb ecosystem
 
 ## Development
 

data/lib/light_service/validated_context/context.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-module ValidatedContext
-  module Context
-    def define_accessor_methods_for_keys(keys)
-      super keys.map(&:to_sym)
+module LightService
+  module ValidatedContext
+    module Context
+      def define_accessor_methods_for_keys(keys)
+        super keys.map(&:to_sym)
+      end
     end
   end
 end

data/lib/light_service/validated_context/expected_key_verifier.rb

@@ -1,31 +1,31 @@
 # frozen_string_literal: true
 
-module ValidatedContext
-  module ExpectedKeyVerifier
-    def keys
-      keys_as_symbols
-    end
+module LightService
+  module ValidatedContext
+    module ExpectedKeyVerifier
+      def keys
+        keys_as_symbols
+      end
 
-    def keys_as_symbols
-      action.expected_keys.map do |key|
-        next key unless key.is_a?(LightService::Context::ValidatedKey)
+      def keys_as_symbols
+        action.expected_keys.map do |key|
+          next key unless key.is_a?(LightService::Context::ValidatedKey)
 
-        key.to_sym
+          key.to_sym
+        end
       end
-    end
 
-    def raw_keys
-      action.expected_keys
-    end
-
-    def throw_error_predicate(keys)
-      type_check_and_coerce_keys!(raw_keys)
+      def raw_keys
+        action.expected_keys
+      end
 
-      keys_are_all_present = are_all_keys_in_context?(keys)
+      def throw_error_predicate(_keys)
+        type_check_and_coerce_keys!(raw_keys)
 
-      return false if are_all_keys_valid? && keys_are_all_present
+        return false if are_all_keys_valid?
 
-      true
+        should_throw_on_validation_error?
+      end
     end
   end
 end

data/lib/light_service/validated_context/fail_on_validation_error.rb

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

data/lib/light_service/validated_context/key_verifier.rb

@@ -1,29 +1,50 @@
 # frozen_string_literal: true
 
-module ValidatedContext
-  module KeyVerifier
-    def type_check_and_coerce_keys!(keys)
-      errors = []
-
-      keys.each do |key|
-        next unless key.is_a?(LightService::Context::ValidatedKey)
-
-        begin
-          context[key.label] = key.type[context[key.label] || Dry::Types::Undefined]
-        rescue Dry::Types::CoercionError => e
-          errors << "[#{action}][:#{key.label}] #{e.message}"
+module LightService
+  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 = []
+
+        keys.each do |key|
+          next unless key.is_a?(LightService::Context::ValidatedKey)
+
+          begin
+            context[key.label] = key.type[context[key.label] || Dry::Types::Undefined]
+          rescue Dry::Types::CoercionError => e
+            errors << (
+              LightService::Configuration.localization_adapter.failure(key.message, action) ||
+                "[#{action}][:#{key.label}] #{e.message}"
+            )
+          end
         end
+
+        @validation_errors = errors
       end
-      # debugger
-      @validation_errors = errors
-    end
+      # rubocop:enable Metrics/AbcSize
 
-    def are_all_keys_valid?
-      @validation_errors.none?
-    end
+      def are_all_keys_valid?
+        @validation_errors.none?
+      end
+
+      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?
 
-    def error_message
-      @validation_errors.join(', ')
+        context.fail!(error_message)
+        false
+      end
     end
   end
 end

data/lib/light_service/validated_context/promised_key_verifier.rb

@@ -1,31 +1,31 @@
 # frozen_string_literal: true
 
-module ValidatedContext
-  module PromisedKeyVerifier
-    def keys
-      keys_as_symbols
-    end
+module LightService
+  module ValidatedContext
+    module PromisedKeyVerifier
+      def keys
+        keys_as_symbols
+      end
 
-    def keys_as_symbols
-      raw_keys.map do |key|
-        next key unless key.is_a?(LightService::Context::ValidatedKey)
+      def keys_as_symbols
+        raw_keys.map do |key|
+          next key unless key.is_a?(LightService::Context::ValidatedKey)
 
-        key.to_sym
+          key.to_sym
+        end
       end
-    end
 
-    def raw_keys
-      action.promised_keys
-    end
-
-    def throw_error_predicate(keys)
-      type_check_and_coerce_keys!(raw_keys)
+      def raw_keys
+        action.promised_keys
+      end
 
-      keys_are_all_present = are_all_keys_in_context?(keys)
+      def throw_error_predicate(_keys)
+        type_check_and_coerce_keys!(raw_keys)
 
-      return false if are_all_keys_valid? && keys_are_all_present
+        return false if are_all_keys_valid?
 
-      true
+        should_throw_on_validation_error?
+      end
     end
   end
 end

data/lib/light_service/validated_context/validated_key.rb

@@ -1,13 +1,23 @@
 # frozen_string_literal: true
 
-module ValidatedContext
-  ValidatedKey = Struct.new(:label, :type) do
-    def to_sym
-      label.to_sym
-    end
+module LightService
+  module ValidatedContext
+    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
 
-    def to_s
-      label.to_s
+      def to_s
+        label.to_s
+      end
     end
   end
 end

data/lib/light_service/validated_context/version.rb

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

data/lib/light_service/validated_context.rb

@@ -1,29 +1,35 @@
 # frozen_string_literal: true
 
 require "zeitwerk"
-loader = Zeitwerk::Loader.for_gem
+loader = Zeitwerk::Loader.new
+loader.tag = 'LightService::I18n'
+loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
+loader.push_dir(__dir__, :namespace => LightService)
 loader.setup
 
 require 'light-service'
 require 'dry-types'
 
-module ValidatedContext; end
+module LightService
+  module ValidatedContext; end
+end
 
 module LightService
   class Context
-    ValidatedKey = ::ValidatedContext::ValidatedKey
-    prepend ::ValidatedContext::Context
+    ValidatedKey = LightService::ValidatedContext::ValidatedKey
+    FailOnValidationError = LightService::ValidatedContext::FailOnValidationError
+    prepend LightService::ValidatedContext::Context
 
     class KeyVerifier
-      prepend ::ValidatedContext::KeyVerifier
+      prepend LightService::ValidatedContext::KeyVerifier
     end
 
     class ExpectedKeyVerifier
-      prepend ::ValidatedContext::ExpectedKeyVerifier
+      prepend LightService::ValidatedContext::ExpectedKeyVerifier
     end
 
     class PromisedKeyVerifier
-      prepend ::ValidatedContext::PromisedKeyVerifier
+      prepend LightService::ValidatedContext::PromisedKeyVerifier
     end
   end
 
@@ -32,7 +38,7 @@ module LightService
   end
 end
 
-# Convenience namespace for implementor
+# Convenience alias for implementor
 Types = LightService::Types unless Module.const_defined?('Types')
 
 # Convenience alias for implementor

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.1
 platform: ruby
 authors:
 - "'Alessandro Fazzi'"
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-30 00:00:00.000000000 Z
+date: 2022-12-08 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