u-case 5.3.1 → 5.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 936bb237d3decf217151d48e7f32339ac698d65bde22930a05e4b90e92d760ea
-  data.tar.gz: e9ecc10a25c778a1393f803bd32ad6ebf7481c1a9144a4d0ac0fce843aed53d2
+  metadata.gz: 0dd8852d56fd022780ae18b61d849649c84080c4fe2a681aca031d3b0c43b139
+  data.tar.gz: 8d9196aee650c25efc8bedc701cbcc1f190e14ea4c8ca97ea6f2f22b3c09259c
 SHA512:
-  metadata.gz: 5a17f2832229d00b96976ebd9d75053b2a0790625ebc8323e2d2def3d7f90d8aa78a255c834a53e7dcf88b578c9c7ba294a1097b317d0a0f74a579f1c29986a4
-  data.tar.gz: 5a357a9a1cbcd6487c62259f85316304348171de648d1bdf35193b92a2952bfc9a51d98d4e16f0572eb7d4e64e12d1c511e161235b3a092176712abcc5e87157
+  metadata.gz: a7b9beee649d540efdbae0553139f09fc4a9053390db61c98c5fd0a3a81569ea7ab60a6db0218f7842f38eabd90f2f0bdec86c717ee473f5692143a1ae44746d
+  data.tar.gz: 1ade9a482e232dfdd5a1976aeb2e47f0b2a5f129bdb965911f7cfda233b2f99f0e34fae97a3402770700bb367a32ded882b1a4b7727c5aae2d7ad0680d863c32

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 > **Note:** This gem was originally published as `u-service` (versions 0.1.0 – 1.0.0) and renamed to `u-case` starting with `u-case 1.0.0` on 2019-09-15.
 
+## [5.4.0] - 2026-05-24
+### Added
+- `Micro::Case.config.disable_runtime_checks` config (default `false`) to skip the gem's internal argument/contract checks for better performance in production. All checks are consolidated in `Micro::Case::Check::Enabled` (the default) and `Micro::Case::Check::Disabled` (no-ops with the same signature); the active module is swapped via `Micro::Case.check`. Measured throughput win is JIT-dependent: within noise on stock Ruby (no JIT), ~3–5% on Ruby 3.2 +YJIT, ~4–7% on Ruby 4.0 +PRISM (see `benchmarks/perfomance/runtime_checks/compare.rb`). Closes #45.
+- `benchmarks/perfomance/runtime_checks/` — per-mode subprocess benchmark (`checks_enabled.rb`, `checks_disabled.rb`, `compare.rb`) demonstrating the toggle's perf effect across Ruby versions and JIT modes.
+
 ## [5.3.1] - 2026-05-23
 ### Added
 - This `CHANGELOG.md`, covering the full history of the gem (from `u-service 0.1.0` through `u-case 5.3.1`) following the [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) spec.
@@ -463,6 +468,7 @@ First release under the `u-case` name (renamed from `u-service`).
 - `Micro::Service::Result` with `Success`/`Failure` factories and helper methods for returning typed results from services.
 - Runtime dependency on `u-attributes` for service input declaration.
 
+[5.4.0]: https://github.com/serradura/u-case/compare/v5.3.1...v5.4.0
 [5.3.1]: https://github.com/serradura/u-case/compare/v5.3.0...v5.3.1
 [5.3.0]: https://github.com/serradura/u-case/compare/v5.2.1...v5.3.0
 [5.2.1]: https://github.com/serradura/u-case/compare/v5.2.0...v5.2.1

data/CLAUDE.md

@@ -93,6 +93,44 @@ Both files are user-facing — keep them in sync with the code:
   translations of each other and must stay in lockstep. If you change a
   documented API, update both READMEs in the same commit.
 
+## Internal argument checks live in `Micro::Case::Check`
+
+Every internal argument/contract check that runs inside the gem (type
+guards, "is this a `Micro::Case`?", "is this a `Symbol`?", "are these
+flow args valid?", etc.) lives in `lib/micro/case/check.rb`, split across
+two modules with **identical method signatures**:
+
+- `Micro::Case::Check::Enabled` — the default; raises the curated
+  `Micro::Case::Error::*` exceptions.
+- `Micro::Case::Check::Disabled` — no-ops (the matching method just
+  `return`s; passthrough methods return their input unchanged).
+
+The active one is referenced as `Micro::Case.check`, swapped by
+`config.disable_runtime_checks = true/false` (see PR #145 / issue #45).
+
+### When you add a new internal check, you must:
+
+1. **Add the method to BOTH modules.** Keep the signature identical.
+   The `Enabled` side does the real work; the `Disabled` side is a
+   no-op (or passthrough for `hash!`-style coercions).
+2. **Route the call site through `Micro::Case.check.<method>!(...)`.**
+   Don't `raise ... unless ...` inline — that bypasses the toggle and
+   leaks the check into the disabled-path performance budget.
+3. **Cover both modes in a test.** Mirror the pattern in
+   `test/micro/case/disable_runtime_checks_test.rb`: one test that the
+   `Enabled` side raises, one that the `Disabled` side does not.
+4. **Avoid extra allocation on the call site.** If the curated
+   exception needs dynamic params (a class name, a context string),
+   pass the raw strings/values into the check method and construct the
+   exception inside `Enabled` (only on the raise path). Don't build the
+   exception before calling — that defeats the perf rationale of the
+   `Disabled` side.
+
+This is the only place where new gem-internal checks belong. Inline
+`raise … unless …` inside the runtime call path is a regression of
+this design — flag it during review and move the check into
+`Micro::Case::Check`.
+
 ## Bumping the version
 
 1. Edit `lib/micro/case/version.rb` — change `Micro::Case::VERSION`. Follow

data/README.md

@@ -27,7 +27,7 @@ The main project goals are:
 Version   | Documentation
 --------- | -------------
 unreleased| https://github.com/serradura/u-case/blob/main/README.md
-5.3.1     | https://github.com/serradura/u-case/blob/v5.x/README.md
+5.4.0     | https://github.com/serradura/u-case/blob/v5.x/README.md
 4.5.1     | https://github.com/serradura/u-case/blob/v4.x/README.md
 
 > **Note:** Você entende português? 🇧🇷 🇵🇹 Verifique o [README traduzido em pt-BR](https://github.com/serradura/u-case/blob/main/README.pt-BR.md).
@@ -90,7 +90,7 @@ unreleased| https://github.com/serradura/u-case/blob/main/README.md
 | u-case           | branch | ruby     | activemodel    | u-attributes   |
 | ---------------- | ------ | -------- | -------------- | -------------- |
 | unreleased       | main   | >= 2.7   | >= 6.0         | >= 2.8, < 4.0  |
-| 5.3.1            | v5.x   | >= 2.7   | >= 6.0         | >= 2.8, < 4.0  |
+| 5.4.0            | v5.x   | >= 2.7   | >= 6.0         | >= 2.8, < 4.0  |
 | 5.1.0            | v5.x   | >= 2.7   | >= 6.0         | >= 2.7, < 4.0  |
 | 4.5.1            | v4.x   | >= 2.2.0 | >= 3.2, <= 8.1 | >= 2.7, < 3.0  |
 
@@ -1256,9 +1256,22 @@ Micro::Case.config do |config|
   #   - Calling `Micro::Cases.safe_flow(...)`
   #   - Calling `Micro::Case::Result#on_exception`
   config.disable_safe_features = false
+
+  # Use to skip the gem's internal argument/contract checks (e.g., "is this a
+  # Micro::Case?", "is the result type a Symbol?", "is the use case a kind of
+  # Micro::Case?"). Set to `true` in production for a small performance boost
+  # once your code paths are exercised by your test suite. The trade-off is that
+  # incorrect usage will surface as confusing downstream errors instead of the
+  # gem's curated ones (e.g. `Micro::Case::Error::InvalidUseCase`).
+  config.disable_runtime_checks = false
 end
 ```
 
+All checks are consolidated in `Micro::Case::Check::Enabled` (the default).
+Toggling `disable_runtime_checks = true` swaps `Micro::Case.check` to
+`Micro::Case::Check::Disabled` — a module with the same signature whose
+methods are no-ops — so the validations themselves are not run on each call.
+
 [⬆️ Back to Top](#table-of-contents-)
 
 ## Benchmarks

data/README.pt-BR.md

@@ -27,7 +27,7 @@ Principais objetivos deste projeto:
 Versão    | Documentação
 --------- | -------------
 unreleased| https://github.com/serradura/u-case/blob/main/README.md
-5.3.1     | https://github.com/serradura/u-case/blob/v5.x/README.md
+5.4.0     | https://github.com/serradura/u-case/blob/v5.x/README.md
 4.5.1     | https://github.com/serradura/u-case/blob/v4.x/README.md
 
 ## Índice <!-- omit in toc -->
@@ -88,7 +88,7 @@ unreleased| https://github.com/serradura/u-case/blob/main/README.md
 | u-case           | branch | ruby     | activemodel    | u-attributes   |
 | ---------------- | ------ | -------- | -------------- | -------------- |
 | unreleased       | main   | >= 2.7   | >= 6.0         | >= 2.8, < 4.0  |
-| 5.3.1            | v5.x   | >= 2.7   | >= 6.0         | >= 2.8, < 4.0  |
+| 5.4.0            | v5.x   | >= 2.7   | >= 6.0         | >= 2.8, < 4.0  |
 | 5.1.0            | v5.x   | >= 2.7   | >= 6.0         | >= 2.7, < 4.0  |
 | 4.5.1            | v4.x   | >= 2.2.0 | >= 3.2, <= 8.1 | >= 2.7, < 3.0  |
 
@@ -1257,9 +1257,24 @@ Micro::Case.config do |config|
   #   - Chamar `Micro::Cases.safe_flow(...)`
   #   - Chamar `Micro::Case::Result#on_exception`
   config.disable_safe_features = false
+
+  # Use para pular as verificações internas de argumento/contrato da gem (por
+  # exemplo, "isto é um Micro::Case?", "o tipo do resultado é um Symbol?",
+  # "o use case é um tipo de Micro::Case?"). Defina `true` em produção para
+  # um pequeno ganho de performance depois que seus caminhos de código já
+  # estiverem cobertos pela sua suíte de testes. O custo é que usos
+  # incorretos vão aparecer como erros confusos mais à frente, em vez dos
+  # erros curados pela gem (ex.: `Micro::Case::Error::InvalidUseCase`).
+  config.disable_runtime_checks = false
 end
 ```
 
+Todas as verificações estão consolidadas em `Micro::Case::Check::Enabled` (o
+padrão). Definir `disable_runtime_checks = true` troca `Micro::Case.check` por
+`Micro::Case::Check::Disabled` — um módulo com a mesma assinatura cujos
+métodos não fazem nada — de forma que as validações não são executadas a
+cada chamada.
+
 [⬆️ Voltar para o índice](#índice-)
 
 ## Benchmarks

data/lib/micro/case/check.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Micro
+  class Case
+    module Check
+      module Enabled
+        extend self
+
+        def use_case_or_flow!(arg)
+          raise Error::InvalidUseCase unless ::Micro.case_or_flow?(arg)
+        end
+
+        def micro_case_instance!(arg)
+          raise Error::InvalidUseCase unless arg.is_a?(::Micro::Case)
+        end
+
+        def result_instance!(arg)
+          raise Error::InvalidResultInstance unless arg.is_a?(::Micro::Case::Result)
+        end
+
+        def result_not_defined!(is_defined)
+          raise Error::ResultIsAlreadyDefined if is_defined
+        end
+
+        def result_type!(type)
+          raise Error::InvalidResultType unless type.is_a?(Symbol)
+        end
+
+        def result_data!(data, is_success, type, use_case)
+          raise Error::InvalidResult.new(is_success, type, use_case) unless data
+        end
+
+        def expected_result!(result, context)
+          return if result.is_a?(::Micro::Case::Result)
+
+          raise Error::UnexpectedResult.new(context)
+        end
+
+        def expected_self_result!(actual, expected, context)
+          return if actual.equal?(expected)
+
+          raise Error::UnexpectedResult.new(context)
+        end
+
+        def then_use_case_or_flow!(arg, owner_label)
+          return if ::Micro.case_or_flow?(arg)
+
+          raise Error::InvalidInvocationOfTheThenMethod.new(owner_label)
+        end
+
+        def flow_use_cases!(use_cases)
+          raise Cases::Error::InvalidUseCases if use_cases.none?(&::Micro::Cases::Flow::IsAValidUseCase)
+        end
+
+        def map_args!(args)
+          raise Cases::Error::InvalidUseCases unless ::Micro::Cases::Map.const_get(:HasValidArgs, false)[args]
+        end
+
+        def hash!(arg)
+          Kind::Hash[arg]
+        end
+      end
+
+      module Disabled
+        extend self
+
+        def use_case_or_flow!(_arg); end
+        def micro_case_instance!(_arg); end
+        def result_instance!(_arg); end
+        def result_not_defined!(_is_defined); end
+        def result_type!(_type); end
+        def result_data!(_data, _is_success, _type, _use_case); end
+        def expected_result!(_result, _context); end
+        def expected_self_result!(_actual, _expected, _context); end
+        def then_use_case_or_flow!(_arg, _owner_label); end
+        def flow_use_cases!(_use_cases); end
+        def map_args!(_args); end
+        def hash!(arg); arg; end
+      end
+    end
+  end
+end

data/lib/micro/case/config.rb

@@ -23,6 +23,18 @@ module Micro
         @disable_safe_features = false
       end
 
+      def disable_runtime_checks=(value)
+        @disable_runtime_checks = Kind::Boolean[value]
+
+        ::Micro::Case.check = @disable_runtime_checks ? ::Micro::Case::Check::Disabled : ::Micro::Case::Check::Enabled
+      end
+
+      def disable_runtime_checks
+        return @disable_runtime_checks if defined?(@disable_runtime_checks)
+
+        @disable_runtime_checks = false
+      end
+
       def enable_activemodel_validation=(value)
         return unless Kind::Boolean[value]
 

data/lib/micro/case/result.rb

@@ -174,14 +174,14 @@ module Micro
       end
 
       def __set__(is_success, data, type, use_case)
-        raise Error::InvalidResultType unless type.is_a?(Symbol)
-        raise Error::InvalidUseCase unless use_case.is_a?(::Micro::Case)
+        ::Micro::Case.check.result_type!(type)
+        ::Micro::Case.check.micro_case_instance!(use_case)
 
         @__success, @type, @use_case = is_success, type, use_case
 
         @data = FetchData.call(data).freeze
 
-        raise Micro::Case::Error::InvalidResult.new(is_success, type, use_case) unless @data
+        ::Micro::Case.check.result_data!(@data, is_success, type, use_case)
 
         @__accumulated_data.merge!(@data)
 
@@ -227,7 +227,7 @@ module Micro
             use_case_method = self.use_case.method(use_case)
             __call_method(use_case_method, attributes)
           else
-            raise INVALID_INVOCATION_OF_THE_THEN_METHOD unless ::Micro.case_or_flow?(use_case)
+            ::Micro::Case.check.then_use_case_or_flow!(use_case, 'Micro::Case::Result#')
 
             input = attributes.is_a?(Hash) ? self.data.merge(attributes) : self.data
 
@@ -244,9 +244,9 @@ module Micro
 
           result = fn.arity.zero? ? fn.call : fn.call(__fetch_accessible_attributes)
 
-          return self if result === self
+          ::Micro::Case.check.expected_self_result!(result, self, "#{Result.name}##{expected}")
 
-          raise Error::UnexpectedResult.new("#{Result.name}##{expected}")
+          self
         end
 
         def __call_method(methd, attributes = nil)
@@ -254,9 +254,9 @@ module Micro
 
           result = methd.arity.zero? ? methd.call : methd.call(**__fetch_accessible_attributes)
 
-          return self if result === self
+          ::Micro::Case.check.expected_self_result!(result, self, "#{use_case.class.name}#method(:#{methd.name})")
 
-          raise Error::UnexpectedResult.new("#{use_case.class.name}#method(:#{methd.name})")
+          self
         end
 
         def __success_type?(expected_type)

data/lib/micro/case/version.rb

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

data/lib/micro/case.rb

@@ -11,12 +11,18 @@ module Micro
     require 'micro/case/utils'
     require 'micro/case/error'
     require 'micro/case/result'
+    require 'micro/case/check'
     require 'micro/case/config'
     require 'micro/case/safe'
     require 'micro/case/strict'
 
     require 'micro/cases'
 
+    class << self
+      attr_accessor :check
+    end
+    self.check = Check::Enabled
+
     include Micro::Attributes
     include Micro::Attributes::Features::Accept
 
@@ -46,7 +52,7 @@ module Micro
       else
         return yield_self if !use_case && can_yield_self
 
-        raise INVALID_INVOCATION_OF_THE_THEN_METHOD unless ::Micro.case_or_flow?(use_case)
+        ::Micro::Case.check.then_use_case_or_flow!(use_case, 'Micro::Case.')
 
         self.call.then(use_case)
       end
@@ -169,8 +175,8 @@ module Micro
     end
 
     def __set_result__(result)
-      raise Error::InvalidResultInstance unless result.is_a?(Result)
-      raise Error::ResultIsAlreadyDefined if defined?(@__result)
+      ::Micro::Case.check.result_instance!(result)
+      ::Micro::Case.check.result_not_defined!(defined?(@__result))
 
       @__result = result
 
@@ -180,7 +186,7 @@ module Micro
     private
 
       def call(use_case, defaults = Kind::Empty::HASH)
-        raise Error::InvalidUseCase unless ::Micro.case_or_flow?(use_case)
+        ::Micro::Case.check.use_case_or_flow!(use_case)
 
         input =
           defaults.empty? ? attributes : attributes.merge(Utils::Hashes.stringify_keys(defaults))
@@ -211,9 +217,9 @@ module Micro
 
         result = call!
 
-        return result if result.is_a?(Result)
+        ::Micro::Case.check.expected_result!(result, "#{self.class.name}#call!")
 
-        raise Error::UnexpectedResult.new("#{self.class.name}#call!")
+        result
       end
 
       def __attributes_errors_present?

data/lib/micro/cases/flow.rb

@@ -11,7 +11,7 @@ module Micro
       def self.build(args)
         use_cases = Utils.map_use_cases(args)
 
-        raise Error::InvalidUseCases if use_cases.none?(&IsAValidUseCase)
+        ::Micro::Case.check.flow_use_cases!(use_cases)
 
         new(use_cases)
       end
@@ -63,7 +63,7 @@ module Micro
         else
           return yield_self if !use_case && can_yield_self
 
-          raise_invalid_invocation_of_the_then_method unless ::Micro.case_or_flow?(use_case)
+          ::Micro::Case.check.then_use_case_or_flow!(use_case, "#{self.class.name}#")
 
           self.call.then(use_case)
         end

data/lib/micro/cases/map.rb

@@ -10,7 +10,7 @@ module Micro
       attr_reader :use_cases
 
       def self.build(args)
-        raise Error::InvalidUseCases unless HasValidArgs[args]
+        ::Micro::Case.check.map_args!(args)
 
         new(args)
       end
@@ -30,7 +30,7 @@ module Micro
       end
 
       def call(arg = {})
-        hash = Kind::Hash[arg]
+        hash = ::Micro::Case.check.hash!(arg)
 
         use_cases.map(&GetUseCaseResult[hash])
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: u-case
 version: !ruby/object:Gem::Version
-  version: 5.3.1
+  version: 5.4.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -118,6 +118,7 @@ files:
 - gemfiles/rails_8_1.gemfile
 - gemfiles/rails_edge.gemfile
 - lib/micro/case.rb
+- lib/micro/case/check.rb
 - lib/micro/case/config.rb
 - lib/micro/case/error.rb
 - lib/micro/case/result.rb