u-case 5.6.0 → 5.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5539d3b5cac24a50728c4dd8285e2f36c4a155f344a5f95763b8b02afaa64505
-  data.tar.gz: 794905f57057a6f198200bbd2b5c3c958440b3fa3154366a636025553a084553
+  metadata.gz: bcab602e98bfb71b2bb2439dd162b3401098bfa41b8234ad39a1a7dd6dad5e6a
+  data.tar.gz: 4d975264e714cb751d595bc945915ac1273d486c0dd5ee6ce156076cbe858ba2
 SHA512:
-  metadata.gz: fc924d76d4e1dbc1dc1a2567688a881a17b726b74210ad57277af2fdd7456e02358501d2f34171d0a027227f5e99a2853aad82f64bca2007e18fefc518e3e622
-  data.tar.gz: e20f832a0b48456a653e48710c2444c8649dce2a68477c4299b856b23939074d01457215e6c3290c1e417cd38724318289f27055505d1b2865b90ca4c15fee0d
+  metadata.gz: 3f5107a4329d04aab99e0458fa5784705c78cc648fdaee53be172b306501f824ccf3af5f8c70629b2ad39289745cb5f79ebb39fa95958cc1820d20913f65111a
+  data.tar.gz: 29be61f84a1e4cbdb42f13bbcf72a8f4e3eaf7618300c0f169461adfc21b12a2ad9215e651bc6a9f366fc3658987d19ff3feadfec61609ff3e3d4860e6b7585d

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.7.0] - 2026-05-25
+### Added
+- Pattern matching support on `Micro::Case::Result` via `#deconstruct` and `#deconstruct_keys` (closes #146). Purely additive — no existing API is changed or removed. `#deconstruct` returns `[status, type, data]` where `status` is `:success` or `:failure`, so array patterns like `in [:failure, :invalid_attributes, { invalid_attributes: errors }]` can use the status as a discriminant — mirroring how libraries with separate `Success`/`Failure` classes are pattern-matched, even though `Micro::Case::Result` is a single class. `#deconstruct_keys` exposes `:type`, `:data`, `:result` (alias of `:data` that matches the `Success(result: …)` creation-site vocabulary), `:use_case` and `:transitions` on every result; `:success` is present only on success results and `:failure` only on failure results, and both carry the result `type` symbol as their value so `in { failure: :invalid_attributes }` works. `#deconstruct_keys` honors Ruby's `keys` argument and only computes the requested entries (relevant for `:transitions`, which allocates a duped array).
+- READMEs (EN + pt-BR) document the new pattern under the `Micro::Case::Result` section, including the key table, the `data:` / `result:` alias note, and the intentional shape difference between `#deconstruct` (`[status, type, data]`, used by pattern matching) and `#to_ary` (`[data, type]`, unchanged, used by multi-assignment).
+
 ## [5.6.0] - 2026-05-24
 ### Added
 - `Micro::Cases.flow(transaction: true, steps: [...])` and `Micro::Cases.safe_flow(transaction: true, steps: [...])` to wrap an entire flow in an `ActiveRecord::Base.transaction`. Any step that returns a failure (or, in `safe_flow`, raises) triggers an `ActiveRecord::Rollback`. The same kwargs are accepted by the class-level macro: `class MyCase < Micro::Case; flow(transaction: true, steps: [...]); end` (closes #44).
@@ -495,6 +500,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.7.0]: https://github.com/serradura/u-case/compare/v5.6.0...v5.7.0
 [5.6.0]: https://github.com/serradura/u-case/compare/v5.5.0...v5.6.0
 [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

data/README.md

@@ -46,6 +46,7 @@ unreleased| https://github.com/serradura/u-case/blob/main/README.md
     - [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)
+      - [Using pattern matching to destructure a result](#using-pattern-matching-to-destructure-a-result)
     - [What happens if a result hook was declared multiple times?](#what-happens-if-a-result-hook-was-declared-multiple-times)
     - [How to use the `Micro::Case::Result#then` method?](#how-to-use-the-microcaseresultthen-method)
       - [What does happens when a `Micro::Case::Result#then` receives a block?](#what-does-happens-when-a-microcaseresultthen-receives-a-block)
@@ -502,6 +503,54 @@ Double
 
 [⬆️ Back to Top](#table-of-contents-)
 
+##### Using pattern matching to destructure a result
+
+`Micro::Case::Result` implements [`deconstruct`](https://docs.ruby-lang.org/en/3.4/syntax/pattern_matching_rdoc.html) and [`deconstruct_keys`](https://docs.ruby-lang.org/en/3.4/syntax/pattern_matching_rdoc.html), so Ruby's `case`/`in` pattern matching works out of the box (requires Ruby `>= 2.7`).
+
+```ruby
+result = Divide.call(a: 10, b: 2)
+
+case result
+in { success: _, data: { number: Numeric => number } }
+  puts "got #{number}"
+in { failure: :invalid_attributes, data: { invalid_attributes: errors } }
+  warn "bad input: #{errors.keys.join(", ")}"
+in { failure: :exception, data: { exception: } }
+  warn "boom: #{exception.message}"
+end
+```
+
+The hash patterns expose these keys:
+
+| Key             | Present on        | Value                                                   |
+| --------------- | ----------------- | ------------------------------------------------------- |
+| `success:`      | success only      | the result `type` (e.g. `:ok`)                          |
+| `failure:`      | failure only      | the result `type` (e.g. `:invalid_attributes`)          |
+| `type:`         | always            | the result `type`                                       |
+| `data:`         | always            | the result `data` hash                                  |
+| `result:`       | always            | alias of `data:` (matches the `Success(result: …)` keyword used at the creation site) |
+| `use_case:`     | always            | the use case instance that produced the result          |
+| `transitions:`  | always            | the result `transitions` array                          |
+
+> **Note:** On the **reader** side, `Result#data` is also accessible as `Result#value` (existing alias). On the **pattern-matching** side, the `data:` key is also accessible as `result:` — both refer to the same payload.
+
+`Result#deconstruct` returns a three-element array `[status, type, data]` where `status` is `:success` or `:failure`, so array patterns can use the status as a discriminant — mirroring how libraries with separate `Success`/`Failure` classes are pattern-matched, even though `Micro::Case::Result` is a single class:
+
+```ruby
+case result
+in [:success, :ok, { number: Integer => n }]
+  n
+in [:failure, :invalid_attributes, { invalid_attributes: errors }]
+  # ...
+in [:failure, :exception, { exception: }]
+  # ...
+end
+```
+
+> **Note:** `Result#to_ary` is unchanged and still returns `[data, type]` (used by multi-assignment, e.g. `data, type = result`). Ruby's pattern matching uses `#deconstruct`, so the two hooks intentionally return different shapes.
+
+[⬆️ Back to Top](#table-of-contents-)
+
 #### What happens if a result hook was declared multiple times?
 
 Answer: The hook always will be triggered if it matches the result type.

data/README.pt-BR.md

@@ -44,6 +44,7 @@ unreleased| https://github.com/serradura/u-case/blob/main/README.md
     - [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)
+      - [Usando pattern matching para desestruturar um resultado](#usando-pattern-matching-para-desestruturar-um-resultado)
     - [O que acontece se um hook de resultado for declarado múltiplas vezes?](#o-que-acontece-se-um-hook-de-resultado-for-declarado-múltiplas-vezes)
     - [Como usar o método `Micro::Case::Result#then`?](#como-usar-o-método-microcaseresultthen)
       - [O que acontece quando um `Micro::Case::Result#then` recebe um bloco?](#o-que-acontece-quando-um-microcaseresultthen-recebe-um-bloco)
@@ -501,6 +502,54 @@ Double
 
 [⬆️ Voltar para o índice](#índice-)
 
+##### Usando pattern matching para desestruturar um resultado
+
+`Micro::Case::Result` implementa [`deconstruct`](https://docs.ruby-lang.org/en/3.4/syntax/pattern_matching_rdoc.html) e [`deconstruct_keys`](https://docs.ruby-lang.org/en/3.4/syntax/pattern_matching_rdoc.html), então o pattern matching do Ruby (`case`/`in`) funciona de forma nativa (requer Ruby `>= 2.7`).
+
+```ruby
+result = Divide.call(a: 10, b: 2)
+
+case result
+in { success: _, data: { number: Numeric => number } }
+  puts "deu #{number}"
+in { failure: :invalid_attributes, data: { invalid_attributes: errors } }
+  warn "entrada inválida: #{errors.keys.join(", ")}"
+in { failure: :exception, data: { exception: } }
+  warn "boom: #{exception.message}"
+end
+```
+
+Os hash patterns expõem essas chaves:
+
+| Chave           | Presente em       | Valor                                                                                   |
+| --------------- | ----------------- | --------------------------------------------------------------------------------------- |
+| `success:`      | apenas em sucesso | o `type` do resultado (ex.: `:ok`)                                                      |
+| `failure:`      | apenas em falha   | o `type` do resultado (ex.: `:invalid_attributes`)                                      |
+| `type:`         | sempre            | o `type` do resultado                                                                   |
+| `data:`         | sempre            | o hash de `data` do resultado                                                           |
+| `result:`       | sempre            | apelido de `data:` (combina com a keyword `result:` usada em `Success(result: …)`)      |
+| `use_case:`     | sempre            | a instância de caso de uso que produziu o resultado                                     |
+| `transitions:`  | sempre            | o array de `transitions` do resultado                                                   |
+
+> **Nota:** No lado de **leitura**, `Result#data` também é acessível como `Result#value` (apelido existente). No lado de **pattern matching**, a chave `data:` também é acessível como `result:` — ambas se referem ao mesmo payload.
+
+`Result#deconstruct` retorna um array de três elementos `[status, type, data]`, onde `status` é `:success` ou `:failure`. Isso permite que array patterns usem o status como discriminante — espelhando como bibliotecas com classes `Success`/`Failure` separadas fazem pattern matching, mesmo que `Micro::Case::Result` seja uma classe única:
+
+```ruby
+case result
+in [:success, :ok, { number: Integer => n }]
+  n
+in [:failure, :invalid_attributes, { invalid_attributes: errors }]
+  # ...
+in [:failure, :exception, { exception: }]
+  # ...
+end
+```
+
+> **Nota:** `Result#to_ary` permanece inalterado e ainda retorna `[data, type]` (usado pela atribuição múltipla, ex.: `data, type = result`). O pattern matching do Ruby usa `#deconstruct`, então os dois hooks intencionalmente retornam shapes diferentes.
+
+[⬆️ Voltar para o índice](#índice-)
+
 #### O que acontece se um hook de resultado for declarado múltiplas vezes?
 
 Resposta: Se o tipo do resultado for identificado o hook será sempre executado.

data/lib/micro/case/result.rb

@@ -50,6 +50,32 @@ module Micro
         @__success ? :success : :failure
       end
 
+      def deconstruct
+        [@__success ? :success : :failure, type, data]
+      end
+
+      def deconstruct_keys(keys)
+        if keys.nil?
+          hash = { type: type, data: data, result: data, use_case: use_case, transitions: transitions }
+          hash[@__success ? :success : :failure] = type
+          return hash
+        end
+
+        hash = {}
+        keys.each do |key|
+          case key
+          when :type        then hash[:type]        = type
+          when :data        then hash[:data]        = data
+          when :result      then hash[:result]      = data
+          when :use_case    then hash[:use_case]    = use_case
+          when :transitions then hash[:transitions] = transitions
+          when :success     then hash[:success]     = type if @__success
+          when :failure     then hash[:failure]     = type if !@__success
+          end
+        end
+        hash
+      end
+
       def [](key)
         data[key]
       end

data/lib/micro/case/version.rb

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

metadata

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