u-case 5.2.1 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 007b0e8ba30a51777bce3c5665960238f0fe50d33c04d3102e444dd917d7a762
-  data.tar.gz: d19a095e0540f218bc4a8dba0601999a3decc56a6990be10fe4a5ef7e35e31c8
+  metadata.gz: 68a2fca8a1808ae9a30ffcdca77631507d89de9fd070628442a9860ce1000fc3
+  data.tar.gz: bcdfdac58fd882e5ed1f912e29d8decbf83971638e43acfe62e84a8697530dc9
 SHA512:
-  metadata.gz: f96b58e62d5fa9de89a664b748941ee4762a9bf4f58b83aa7a56fa745b447772b33df24272aa8d49b3768ce6d83a2af9138647baf2d1e704276db2f7ca335cdc
-  data.tar.gz: 6260ad743a4a40da49d0bbd7cea4d5d7aba9ce374bce2df8bc496d61373b11de3c7315017936a8053625ba5298b4e8fb13d03c748ceccdd73c590690bffff366
+  metadata.gz: ef37188a66960746af6613e98c259198e489afb75f25821d15b91cf24cc485b1153f05a80745f702e158f0fcbb0cd84733bccf7fefb0581f03d3c81dbbd69a69
+  data.tar.gz: a89891142cbe3be3cc36ac5cdd22f257d164c47ff1b1a484768b76b9f199590dfb10725985369080a73105db23f42a2d5401ab0a6cd8f977df1cc8b9873e92aa

data/README.md

@@ -60,6 +60,7 @@ unreleased| https://github.com/serradura/u-case/blob/main/README.md
   - [`Micro::Case::Safe` - Is there some feature to auto handle exceptions inside of a use case or flow?](#microcasesafe---is-there-some-feature-to-auto-handle-exceptions-inside-of-a-use-case-or-flow)
     - [`Micro::Cases::Safe::Flow`](#microcasessafeflow)
     - [`Micro::Case::Result#on_exception`](#microcaseresulton_exception)
+    - [Opting out of the safe mechanism](#opting-out-of-the-safe-mechanism)
   - [Validating attributes with `accept:` / `reject:`](#validating-attributes-with-accept--reject)
   - [`u-case/with_activemodel_validation` - How to validate the use case attributes?](#u-casewith_activemodel_validation---how-to-validate-the-use-case-attributes)
     - [If I enabled the auto validation, is it possible to disable it only in specific use cases?](#if-i-enabled-the-auto-validation-is-it-possible-to-disable-it-only-in-specific-use-cases)
@@ -1070,6 +1071,28 @@ As you can see, this hook has the same behavior of `result.on_failure(:exception
 
 [⬆️ Back to Top](#table-of-contents-)
 
+#### Opting out of the safe mechanism
+
+The "safe" mechanism is opinionated: it converts any unhandled exception inside a use case (or any step of a flow) into a failure result with `type: :exception`. That is powerful, but it can also produce a **fragmented codebase**, where some exceptions are handled with `rescue` inside `call!` and others are handled later via `on_exception` / `on_failure(:exception)` — making the control flow hard to reason about.
+
+If you prefer a single, explicit convention for exception handling — namely, plain `rescue` statements inside your use cases — you can disable the safe APIs entirely:
+
+```ruby
+Micro::Case.config do |config|
+  config.disable_safe_features = true
+end
+```
+
+Once enabled, the following will raise `Micro::Case::Error::SafeFeaturesDisabled`, ensuring no one in the codebase can reintroduce the safe path by accident:
+
+- Subclassing `Micro::Case::Safe`
+- Calling `Micro::Cases.safe_flow(...)`
+- Calling `Micro::Case::Result#on_exception`
+
+See [`Micro::Case.config`](#microcaseconfig) for the full list of available toggles.
+
+[⬆️ Back to Top](#table-of-contents-)
+
 ### Validating attributes with `accept:` / `reject:`
 
 Since `u-case 5.2.0`, every use case includes the [`accept` extension](https://github.com/serradura/u-attributes#accept-extension) from [`u-attributes`](https://github.com/serradura/u-attributes) (requires `u-attributes >= 2.8`). You can declare type expectations (or any other check) directly on the attribute, and the use case will fail automatically with the `:invalid_attributes` type when any attribute is rejected — no need to validate inside `call!`.
@@ -1225,6 +1248,14 @@ Micro::Case.config do |config|
 
   # Use to enable/disable the `Micro::Case::Results#transitions`.
   config.enable_transitions = true
+
+  # Use to forbid the "safe" features and ensure a single way to handle exceptions
+  # (via standard `rescue` statements). When set to `true`, the following will raise
+  # `Micro::Case::Error::SafeFeaturesDisabled`:
+  #   - Subclassing `Micro::Case::Safe`
+  #   - Calling `Micro::Cases.safe_flow(...)`
+  #   - Calling `Micro::Case::Result#on_exception`
+  config.disable_safe_features = false
 end
 ```
 

data/README.pt-BR.md

@@ -58,6 +58,7 @@ unreleased| https://github.com/serradura/u-case/blob/main/README.md
   - [`Micro::Case::Safe` - Existe algum recurso para lidar automaticamente com exceções dentro de um caso de uso ou fluxo?](#microcasesafe---existe-algum-recurso-para-lidar-automaticamente-com-exceções-dentro-de-um-caso-de-uso-ou-fluxo)
     - [`Micro::Cases::Safe::Flow`](#microcasessafeflow)
     - [`Micro::Case::Result#on_exception`](#microcaseresulton_exception)
+    - [Desabilitando o mecanismo "safe"](#desabilitando-o-mecanismo-safe)
   - [Validando atributos com `accept:` / `reject:`](#validando-atributos-com-accept--reject)
   - [`u-case/with_activemodel_validation` - Como validar os atributos do caso de uso?](#u-casewith_activemodel_validation---como-validar-os-atributos-do-caso-de-uso)
     - [Se eu habilitei a validação automática, é possível desabilitá-la apenas em casos de uso específicos?](#se-eu-habilitei-a-validação-automática-é-possível-desabilitá-la-apenas-em-casos-de-uso-específicos)
@@ -1071,6 +1072,28 @@ Como você pode ver, este hook tem o mesmo comportamento de `result.on_failure(:
 
 [⬆️ Voltar para o índice](#índice-)
 
+#### Desabilitando o mecanismo "safe"
+
+O mecanismo "safe" é opinativo: ele converte qualquer exceção não tratada dentro de um caso de uso (ou em qualquer passo de um fluxo) em um resultado de falha com `type: :exception`. Isso é poderoso, mas também pode gerar uma **base de código fragmentada**, onde algumas exceções são tratadas com `rescue` dentro do `call!` e outras só são tratadas mais tarde via `on_exception` / `on_failure(:exception)` — tornando o fluxo de controle difícil de acompanhar.
+
+Se você prefere uma única convenção explícita para o tratamento de exceções — `rescue` padrão dentro dos seus casos de uso — é possível desabilitar as APIs "safe" por completo:
+
+```ruby
+Micro::Case.config do |config|
+  config.disable_safe_features = true
+end
+```
+
+Com isso ativo, os usos abaixo levantarão `Micro::Case::Error::SafeFeaturesDisabled`, garantindo que ninguém na base de código reintroduza o caminho "safe" sem querer:
+
+- Herdar de `Micro::Case::Safe`
+- Chamar `Micro::Cases.safe_flow(...)`
+- Chamar `Micro::Case::Result#on_exception`
+
+Veja [`Micro::Case.config`](#microcaseconfig) para a lista completa de configurações disponíveis.
+
+[⬆️ Voltar para o índice](#índice-)
+
 ### Validando atributos com `accept:` / `reject:`
 
 Desde a versão `5.2.0` do `u-case`, todo caso de uso já inclui a [extensão `accept`](https://github.com/serradura/u-attributes#accept-extension) do [`u-attributes`](https://github.com/serradura/u-attributes) (requer `u-attributes >= 2.8`). Você pode declarar a expectativa de tipo (ou qualquer outra verificação) diretamente no atributo, e o caso de uso falhará automaticamente com o tipo `:invalid_attributes` quando algum atributo for rejeitado — sem precisar validar dentro do `call!`.
@@ -1226,6 +1249,14 @@ Micro::Case.config do |config|
 
   # Use para habilitar/desabilitar o `Micro::Case::Results#transitions`.
   config.enable_transitions = true
+
+  # Use para proibir as funcionalidades "safe" e garantir uma única forma de tratar
+  # exceções (via `rescue` padrão). Quando `true`, os itens abaixo levantarão
+  # `Micro::Case::Error::SafeFeaturesDisabled`:
+  #   - Herdar de `Micro::Case::Safe`
+  #   - Chamar `Micro::Cases.safe_flow(...)`
+  #   - Chamar `Micro::Case::Result#on_exception`
+  config.disable_safe_features = false
 end
 ```
 

data/lib/micro/case/config.rb

@@ -13,6 +13,16 @@ module Micro
         )
       end
 
+      def disable_safe_features=(value)
+        @disable_safe_features = Kind::Boolean[value]
+      end
+
+      def disable_safe_features
+        return @disable_safe_features if defined?(@disable_safe_features)
+
+        @disable_safe_features = false
+      end
+
       def enable_activemodel_validation=(value)
         return unless Kind::Boolean[value]
 

data/lib/micro/case/error.rb

@@ -51,6 +51,15 @@ module Micro
         end
       end
 
+      class SafeFeaturesDisabled < StandardError
+        def initialize(context)
+          super(
+            "#{context} can't be used because the safe features are disabled. " \
+            "To re-enable them, set `config.disable_safe_features = false`."
+          )
+        end
+      end
+
       def self.by_wrong_usage?(exception)
         case exception
         when Kind::Error, ArgumentError, InvalidResult, UnexpectedResult then true

data/lib/micro/case/result.rb

@@ -121,6 +121,10 @@ module Micro
       end
 
       def on_exception(expected_exception = nil)
+        if Config.instance.disable_safe_features
+          raise Error::SafeFeaturesDisabled.new('Micro::Case::Result#on_exception')
+        end
+
         return self unless __failure_type?(:exception)
 
         if !expected_exception || (Kind.is?(Exception, expected_exception) && data.fetch(:exception).is_a?(expected_exception))

data/lib/micro/case/safe.rb

@@ -3,6 +3,14 @@
 module Micro
   class Case
     class Safe < ::Micro::Case
+      def self.inherited(subclass)
+        if Config.instance.disable_safe_features
+          raise Error::SafeFeaturesDisabled.new('Micro::Case::Safe')
+        end
+
+        super
+      end
+
       def self.__flow_builder__
         Cases::Safe::Flow
       end

data/lib/micro/case/version.rb

@@ -2,6 +2,6 @@
 
 module Micro
   class Case
-    VERSION = '5.2.1'.freeze
+    VERSION = '5.3.0'.freeze
   end
 end

data/lib/micro/case.rb

@@ -11,9 +11,9 @@ module Micro
     require 'micro/case/utils'
     require 'micro/case/error'
     require 'micro/case/result'
+    require 'micro/case/config'
     require 'micro/case/safe'
     require 'micro/case/strict'
-    require 'micro/case/config'
 
     require 'micro/cases'
 

data/lib/micro/cases.rb

@@ -13,6 +13,10 @@ module Micro
     end
 
     def self.safe_flow(args)
+      if Case::Config.instance.disable_safe_features
+        raise Case::Error::SafeFeaturesDisabled.new('Micro::Cases.safe_flow')
+      end
+
       Safe::Flow.build(args)
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: u-case
 version: !ruby/object:Gem::Version
-  version: 5.2.1
+  version: 5.3.0
 platform: ruby
 authors:
 - Rodrigo Serradura