u-case 5.4.0 → 5.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dd8852d56fd022780ae18b61d849649c84080c4fe2a681aca031d3b0c43b139
-  data.tar.gz: 8d9196aee650c25efc8bedc701cbcc1f190e14ea4c8ca97ea6f2f22b3c09259c
+  metadata.gz: 4e57208798d170fbccde7b54f5beb6220cecbfd70c3983fedcb701070a73c7bc
+  data.tar.gz: e4a0c472d1fd6edacf6ac3495d902ca851a88f5420360b708bdf2f204818cc1a
 SHA512:
-  metadata.gz: a7b9beee649d540efdbae0553139f09fc4a9053390db61c98c5fd0a3a81569ea7ab60a6db0218f7842f38eabd90f2f0bdec86c717ee473f5692143a1ae44746d
-  data.tar.gz: 1ade9a482e232dfdd5a1976aeb2e47f0b2a5f129bdb965911f7cfda233b2f99f0e34fae97a3402770700bb367a32ded882b1a4b7727c5aae2d7ad0680d863c32
+  metadata.gz: 154ce36f3efefa81e8e0dcc191cfd25396a7ad0b431f6d2a8190974036ed21f70faa617cc6834569f7fe02855b712abb33dca1da44285913c578ff73cc7cdfcc
+  data.tar.gz: 20f5e74caf9b58ae935bb39dc9780fd7bcfe21e68f4adbec162cff797284939067b2e254e790a2eb17ac8de3ce7a30460af5908170ba136730fa94b784f84a87

data/CHANGELOG.md

@@ -7,6 +7,16 @@ 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.5.0] - 2026-05-24
+### Added
+- `Micro::Case.results { |on| ... }` macro to declare a results contract — the allowed `Success`/`Failure` types and the result keys each one requires. `Success(...)` / `Failure(...)` calls that use an undeclared type now raise `Micro::Case::Error::UnexpectedResultType`; calls missing a declared required key raise `Micro::Case::Error::MissingResultKeys`. Use cases without a `results` block keep their previous unrestricted behavior. The check routes through `Micro::Case::Check#results_contract!`, so it is also bypassed when `config.disable_runtime_checks = true` (closes #22). Carve-outs so contracts don't break neighbouring features:
+  - Framework-generated `__failure_from_attributes_errors` (the auto-failure produced when `accept:`/`reject:` or ActiveModel validation rejects an input) bypasses the contract — it goes directly to `__set__` rather than through `Failure(...)` — so combining `results` with attribute validation no longer requires declaring `:invalid_attributes`.
+  - Rescued exceptions in `Micro::Case::Safe` (which produce `Failure(result: exception)`) bypass the contract.
+  - Result hashes with `String` keys are matched against the contract's symbolised required keys — `Success(result: { 'value' => 1 })` satisfies `result: [:value]`, mirroring `Result`'s own tolerance for either key type.
+  - Non-`Hash` / non-`Symbol` `result:` arguments fall through to the existing `Micro::Case::Error::InvalidResult` ("must be a Hash") instead of being misreported as missing keys.
+  - Non-`Symbol` `type` arguments fall through to `Micro::Case::Error::InvalidResultType` instead of being misreported as undeclared.
+  - `Micro::Case.results` raises `ArgumentError` when called on the abstract base class itself, so a stray declaration cannot leak a contract to every subclass in the process.
+
 ## [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.
@@ -468,6 +478,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.5.0]: https://github.com/serradura/u-case/compare/v5.4.0...v5.5.0
 [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

data/CLAUDE.md

@@ -90,8 +90,17 @@ Both files are user-facing — keep them in sync with the code:
 - **`README.md` and `README.pt-BR.md`**: the **Documentation** table and the
   **Compatibility** table at the top reference the latest released version
   and its dependency bounds. Update both files together — they are
-  translations of each other and must stay in lockstep. If you change a
-  documented API, update both READMEs in the same commit.
+  translations of each other and must stay in lockstep. Any user-visible
+  API change requires a README update in the same commit:
+  - **New public API** (new macro, new module-level method, new public
+    instance method, new error class users can rescue, new config option) —
+    add or extend the relevant section in both READMEs with an example.
+  - **Changed documented API** — update the existing section in both
+    READMEs to match the new behavior.
+  - **Removed/deprecated API** — remove or mark the section in both
+    READMEs.
+  - Pure internal refactors, CI tweaks, and test-only changes don't need
+    README updates.
 
 ## Internal argument checks live in `Micro::Case::Check`
 

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.4.0     | https://github.com/serradura/u-case/blob/v5.x/README.md
+5.5.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).
@@ -42,6 +42,7 @@ unreleased| https://github.com/serradura/u-case/blob/main/README.md
     - [What are the default result types?](#what-are-the-default-result-types)
     - [How to define custom result types?](#how-to-define-custom-result-types)
     - [Is it possible to define a custom type without a result data?](#is-it-possible-to-define-a-custom-type-without-a-result-data)
+    - [How to declare a results contract?](#how-to-declare-a-results-contract)
     - [How to use the result hooks?](#how-to-use-the-result-hooks)
     - [Why the hook usage without a defined type exposes the result itself?](#why-the-hook-usage-without-a-defined-type-exposes-the-result-itself)
       - [Using decomposition to access the result data and type](#using-decomposition-to-access-the-result-data-and-type)
@@ -90,7 +91,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.4.0            | v5.x   | >= 2.7   | >= 6.0         | >= 2.8, < 4.0  |
+| 5.5.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  |
 
@@ -335,6 +336,58 @@ result.use_case.attributes # {"a"=>2, "b"=>"2"}
 
 [⬆️ Back to Top](#table-of-contents-)
 
+#### How to declare a results contract?
+
+Answer: Use the `results do |on| ... end` macro to declare which result types your use case can return, and which keys each one requires. When a contract is declared, `Success(...)` / `Failure(...)` calls that use an undeclared type raise `Micro::Case::Error::UnexpectedResultType`, and calls that omit a declared required key raise `Micro::Case::Error::MissingResultKeys`.
+
+```ruby
+class Divide < Micro::Case
+  attributes :a, :b
+
+  results do |on|
+    on.failure(:attributes_must_be_numbers)
+    on.failure(:division_by_zero)
+
+    on.success(result: [:division])
+  end
+
+  def call!
+    return Failure(:attributes_must_be_numbers) unless Kind.of?(Numeric, a, b)
+    return Failure(:division_by_zero) if b == 0
+
+    Success result: { division: a / b }
+  end
+end
+
+Divide.call(a: 10, b: 2).data # => { division: 5 }
+Divide.call(a: 10, b: 0).type # => :division_by_zero
+Divide.call(a: 'x', b: 2).type # => :attributes_must_be_numbers
+```
+
+A type passed to `on.success` / `on.failure` without a `result:` argument declares the type with no required keys (any payload — including the implicit `{ type => true }` from `Failure(:my_type)` — is accepted). When `result: [:key1, :key2]` is given, those keys must be present in the result hash; extra keys are allowed.
+
+```ruby
+class Wrong < Micro::Case
+  results do |on|
+    on.success(result: [:value])
+    on.failure(:known)
+  end
+
+  def call!
+    Success(:other, result: { value: 1 })   # raises Micro::Case::Error::UnexpectedResultType
+    # Success(result: { wrong: 1 })         # raises Micro::Case::Error::MissingResultKeys
+    # Failure(:other)                       # raises Micro::Case::Error::UnexpectedResultType
+  end
+end
+```
+
+Notes:
+- Use cases without a `results` block keep their previous unrestricted behavior — the contract is opt-in.
+- Subclasses inherit the parent's contract.
+- Rescued exceptions in `Micro::Case::Safe` (which produce `Failure(result: exception)` automatically) bypass the contract.
+
+[⬆️ Back to Top](#table-of-contents-)
+
 #### How to use the result hooks?
 
 As [mentioned earlier](#microcaseresult---what-is-a-use-case-result), the `Micro::Case::Result` has two methods to improve the application flow control. They are: `#on_success`, `on_failure`.

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.4.0     | https://github.com/serradura/u-case/blob/v5.x/README.md
+5.5.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 -->
@@ -40,6 +40,7 @@ unreleased| https://github.com/serradura/u-case/blob/main/README.md
     - [O que são os tipos de resultados?](#o-que-são-os-tipos-de-resultados)
     - [Como definir tipos customizados de resultados?](#como-definir-tipos-customizados-de-resultados)
     - [É possível definir um tipo sem definir os dados do resultado?](#é-possível-definir-um-tipo-sem-definir-os-dados-do-resultado)
+    - [Como declarar um contrato de resultados?](#como-declarar-um-contrato-de-resultados)
     - [Como utilizar os hooks dos resultados?](#como-utilizar-os-hooks-dos-resultados)
     - [Por que o hook sem um tipo definido expõe o próprio resultado?](#por-que-o-hook-sem-um-tipo-definido-expõe-o-próprio-resultado)
       - [Usando decomposição para acessar os dados e tipo do resultado](#usando-decomposição-para-acessar-os-dados-e-tipo-do-resultado)
@@ -88,7 +89,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.4.0            | v5.x   | >= 2.7   | >= 6.0         | >= 2.8, < 4.0  |
+| 5.5.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  |
 
@@ -333,6 +334,58 @@ result.use_case.attributes # {"a"=>2, "b"=>"2"}
 
 [⬆️ Voltar para o índice](#índice-)
 
+#### Como declarar um contrato de resultados?
+
+Resposta: Utilize a macro `results do |on| ... end` para declarar quais tipos de resultado o caso de uso pode retornar e quais chaves cada um exige. Quando há um contrato declarado, chamadas a `Success(...)` / `Failure(...)` que usem um tipo não declarado levantam `Micro::Case::Error::UnexpectedResultType`, e chamadas que omitam uma chave obrigatória declarada levantam `Micro::Case::Error::MissingResultKeys`.
+
+```ruby
+class Divide < Micro::Case
+  attributes :a, :b
+
+  results do |on|
+    on.failure(:attributes_must_be_numbers)
+    on.failure(:division_by_zero)
+
+    on.success(result: [:division])
+  end
+
+  def call!
+    return Failure(:attributes_must_be_numbers) unless Kind.of?(Numeric, a, b)
+    return Failure(:division_by_zero) if b == 0
+
+    Success result: { division: a / b }
+  end
+end
+
+Divide.call(a: 10, b: 2).data # => { division: 5 }
+Divide.call(a: 10, b: 0).type # => :division_by_zero
+Divide.call(a: 'x', b: 2).type # => :attributes_must_be_numbers
+```
+
+Um tipo declarado em `on.success` / `on.failure` sem o argumento `result:` é aceito sem chaves obrigatórias (qualquer payload — inclusive o implícito `{ tipo => true }` de `Failure(:meu_tipo)` — é aceito). Quando `result: [:chave_1, :chave_2]` é informado, essas chaves precisam estar presentes no hash de resultado; chaves extras são permitidas.
+
+```ruby
+class Wrong < Micro::Case
+  results do |on|
+    on.success(result: [:value])
+    on.failure(:known)
+  end
+
+  def call!
+    Success(:other, result: { value: 1 })   # levanta Micro::Case::Error::UnexpectedResultType
+    # Success(result: { wrong: 1 })         # levanta Micro::Case::Error::MissingResultKeys
+    # Failure(:other)                       # levanta Micro::Case::Error::UnexpectedResultType
+  end
+end
+```
+
+Notas:
+- Casos de uso sem o bloco `results` mantêm o comportamento anterior sem restrições — o contrato é opt-in.
+- Subclasses herdam o contrato declarado na classe pai.
+- Exceções capturadas em `Micro::Case::Safe` (que geram `Failure(result: exception)` automaticamente) são exemptas do contrato.
+
+[⬆️ Voltar para o índice](#índice-)
+
 #### Como utilizar os hooks dos resultados?
 
 Como [mencionando anteriormente](#microcaseresult---o-que-é-o-resultado-de-um-caso-de-uso), o `Micro::Case::Result` tem dois métodos para melhorar o controle do fluxo da aplicação. São eles:

data/lib/micro/case/check.rb

@@ -59,6 +59,38 @@ module Micro
         def hash!(arg)
           Kind::Hash[arg]
         end
+
+        def results_contract!(use_case_class, kind, type, value)
+          contract = use_case_class.__results_contract__
+          return unless contract
+          return unless type.is_a?(Symbol)
+          return if value.is_a?(Exception)
+
+          if kind == :success
+            declared = contract.success_declared?(type)
+            declared_types = contract.successes.keys
+            required = contract.success_keys(type) if declared
+          else
+            declared = contract.failure_declared?(type)
+            declared_types = contract.failures.keys
+            required = contract.failure_keys(type) if declared
+          end
+
+          raise Error::UnexpectedResultType.new(use_case_class, kind, type, declared_types) unless declared
+          return if required.nil? || required.empty?
+
+          if value.is_a?(Hash)
+            data_keys = value.keys.map { |k| k.is_a?(String) ? k.to_sym : k }
+          elsif value.is_a?(Symbol)
+            data_keys = [type]
+          else
+            return
+          end
+
+          missing = required - data_keys
+
+          raise Error::MissingResultKeys.new(use_case_class, kind, type, missing) unless missing.empty?
+        end
       end
 
       module Disabled
@@ -76,6 +108,7 @@ module Micro
         def flow_use_cases!(_use_cases); end
         def map_args!(_args); end
         def hash!(arg); arg; end
+        def results_contract!(_use_case_class, _kind, _type, _value); end
       end
     end
   end

data/lib/micro/case/error.rb

@@ -60,9 +60,32 @@ module Micro
         end
       end
 
+      class UnexpectedResultType < TypeError
+        def initialize(use_case_class, kind, type, declared_types)
+          declared_list = declared_types.map { |t| ":#{t}" }.join(', ')
+          declared_list = '(none)' if declared_list.empty?
+
+          super(
+            "#{use_case_class.name} declared a results contract — " \
+            "#{kind} type :#{type} is not declared. Declared #{kind} types: #{declared_list}."
+          )
+        end
+      end
+
+      class MissingResultKeys < ArgumentError
+        def initialize(use_case_class, kind, type, missing_keys)
+          missing_list = missing_keys.map { |k| ":#{k}" }.join(', ')
+
+          super(
+            "#{use_case_class.name} declared a results contract — " \
+            "#{kind} :#{type} is missing required result keys: #{missing_list}."
+          )
+        end
+      end
+
       def self.by_wrong_usage?(exception)
         case exception
-        when Kind::Error, ArgumentError, InvalidResult, UnexpectedResult then true
+        when Kind::Error, ArgumentError, InvalidResult, UnexpectedResult, UnexpectedResultType then true
         else false
         end
       end

data/lib/micro/case/result/contract.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Micro
+  class Case
+    class Result
+      class Contract
+        attr_reader :successes, :failures
+
+        def self.define(&block)
+          contract = new
+          block.call(Definition.new(contract))
+          contract
+        end
+
+        def initialize
+          @successes = {}
+          @failures = {}
+        end
+
+        def add_success(type, keys)
+          @successes[type] = Array(keys).map(&:to_sym)
+        end
+
+        def add_failure(type, keys)
+          @failures[type] = Array(keys).map(&:to_sym)
+        end
+
+        def success_declared?(type)
+          @successes.key?(type)
+        end
+
+        def failure_declared?(type)
+          @failures.key?(type)
+        end
+
+        def success_keys(type)
+          @successes[type]
+        end
+
+        def failure_keys(type)
+          @failures[type]
+        end
+
+        class Definition
+          def initialize(contract)
+            @contract = contract
+          end
+
+          def success(type = :ok, result: nil)
+            @contract.add_success(Kind::Symbol[type], result)
+          end
+
+          def failure(type = :error, result: nil)
+            @contract.add_failure(Kind::Symbol[type], result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/micro/case/version.rb

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

data/lib/micro/case.rb

@@ -11,6 +11,7 @@ module Micro
     require 'micro/case/utils'
     require 'micro/case/error'
     require 'micro/case/result'
+    require 'micro/case/result/contract'
     require 'micro/case/check'
     require 'micro/case/config'
     require 'micro/case/safe'
@@ -66,6 +67,20 @@ module Micro
       @__flow_use_cases = Cases::Utils.map_use_cases(args)
     end
 
+    def self.results(&block)
+      raise ArgumentError, 'a block is required'.freeze unless block
+      raise ArgumentError, 'must be called on a Micro::Case subclass, not on Micro::Case itself'.freeze if self == ::Micro::Case
+
+      @__results_contract = Result::Contract.define(&block)
+    end
+
+    def self.__results_contract__
+      return @__results_contract if defined?(@__results_contract)
+
+      parent = superclass
+      parent.respond_to?(:__results_contract__) ? parent.__results_contract__ : nil
+    end
+
     class << self
       alias __call__ call
 
@@ -227,9 +242,10 @@ module Micro
       end
 
       def __failure_from_attributes_errors
-        Failure(
-          Config.instance.activemodel_validation_errors_failure,
-          result: { errors: attributes_errors }
+        __get_result(
+          false,
+          { errors: attributes_errors },
+          Config.instance.activemodel_validation_errors_failure
         )
       end
 
@@ -244,6 +260,8 @@ module Micro
       def Success(type = :ok, result: nil)
         value = result || type
 
+        ::Micro::Case.check.results_contract!(self.class, :success, type, value)
+
         __get_result(true, value, type)
       end
 
@@ -260,10 +278,11 @@ module Micro
 
         type = MapFailureType.call(value, type)
 
+        ::Micro::Case.check.results_contract!(self.class, :failure, type, value)
+
         __get_result(false, value, type)
       end
 
-
       def Check(type = nil, result: nil, on: Kind::Empty::HASH)
         result_key = type || :check
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: u-case
 version: !ruby/object:Gem::Version
-  version: 5.4.0
+  version: 5.5.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -122,6 +122,7 @@ files:
 - lib/micro/case/config.rb
 - lib/micro/case/error.rb
 - lib/micro/case/result.rb
+- lib/micro/case/result/contract.rb
 - lib/micro/case/result/transitions.rb
 - lib/micro/case/result/wrapper.rb
 - lib/micro/case/safe.rb