Update README (WIP)

README.md

@@ -108,11 +108,11 @@ class Multiply < Micro::Case
  # 2. Define the method `call!` with its business logic
  def call!
 
- # 3. Wrap the use case result/output using the `Success()` or `Failure()` methods
+ # 3. Wrap the use case result/output using the `Success(result: *)` or `Failure(result: *)` methods
  if a.is_a?(Numeric) && b.is_a?(Numeric)
- Success(a * b)
+ Success result: { number: a * b }
  else
- Failure { '`a` and `b` attributes must be numeric' }
+ Failure result: { message: '`a` and `b` attributes must be numeric' }
  end
  end
 end
@@ -126,22 +126,22 @@ end
 result = Multiply.call(a: 2, b: 2)
 
 result.success? # true
-result.value # 4
+result.data  # { number: 4 }
 
 # Failure result
 
 bad_result = Multiply.call(a: 2, b: '2')
 
 bad_result.failure? # true
-bad_result.value # "`a` and `b` attributes must be numeric"
+bad_result.data  # { message: "`a` and `b` attributes must be numeric" }
 
 #-----------------------------#
 # Calling a use case instance #
 #-----------------------------#
 
 result = Multiply.new(a: 2, b: 3).call
 
-result.value # 6
+result.value # { number: 6 }
 
 # Note:
 # ----
@@ -156,11 +156,13 @@ result.value # 6
 A `Micro::Case::Result` stores the use cases output data. These are their main methods:
 - `#success?` returns true if is a successful result.
 - `#failure?` returns true if is an unsuccessful result.
-- `#value` the result value itself.
+- `#data` the result data itself.
 - `#type` a Symbol which gives meaning for the result, this is useful to declare different types of failures or success.
-- `#on_success` or `#on_failure` are hook methods that help you define the application flow.
+- `#on_success` or `#on_failure` are hook methods that help you to define the application flow.
 - `#use_case` if is a failure result, the use case responsible for it will be accessible through this method. This feature is handy to handle a flow failure (this topic will be covered ahead).
-- `#then` allows if the current result is a success, the `then` method will allow to applying a new use case for its value.
+- `#then` this method will allow applying a new use case if the current result was a success. The idea of this feature is to allow the creation of dynamic flows.
+
+> **Note:** for backward compatibility, you could use the `#value` method as an alias of `#data` method.
 
 [⬆️ Back to Top](#table-of-contents-)
 
@@ -175,9 +177,13 @@ class Divide < Micro::Case
  attributes :a, :b
 
  def call!
- invalid_attributes.empty? ? Success(a / b) : Failure(invalid_attributes)
- rescue => e
- Failure(e)
+ if invalid_attributes.empty?
+ Success result: { number: a / b }
+ else
+ Failure result: { invalid_attributes: invalid_attributes }
+ end
+ rescue => exception
+ Failure result: exception
  end
 
  private def invalid_attributes
@@ -190,7 +196,7 @@ end
 result = Divide.call(a: 2, b: 2)
 
 result.type # :ok
-result.value # 1
+result.data  # { number: 1 }
 result.success? # true
 result.use_case # raises `Micro::Case::Error::InvalidAccessToTheUseCaseObject: only a failure result can access its own use case`
 
@@ -199,7 +205,7 @@ result.use_case # raises `Micro::Case::Error::InvalidAccessToTheUseCaseObject: o
 bad_result = Divide.call(a: 2, b: '2')
 
 bad_result.type # :error
-bad_result.value # {"b"=>"2"}
+bad_result.data  # { invalid_attributes: { "b"=>"2" } }
 bad_result.failure? # true
 bad_result.use_case # #<Divide:0x0000 @__attributes={"a"=>2, "b"=>"2"}, @a=2, @b="2", @__result=#<Micro::Case::Result:0x0000 @use_case=#<Divide:0x0000 ...>, @type=:error, @value={"b"=>"2"}, @success=false>
 
@@ -208,31 +214,33 @@ bad_result.use_case # #<Divide:0x0000 @__attributes={"a"=>2, "b"=>"2"}, @a=2, @b
 err_result = Divide.call(a: 2, b: 0)
 
 err_result.type # :exception
-err_result.value # <ZeroDivisionError: divided by 0>
+err_result.data  # { exception: <ZeroDivisionError: divided by 0> }
 err_result.failure? # true
 err_result.use_case # #<Divide:0x0000 @__attributes={"a"=>2, "b"=>0}, @a=2, @b=0, @__result=#<Micro::Case::Result:0x0000 @use_case=#<Divide:0x0000 ...>, @type=:exception, @value=#<ZeroDivisionError: divided by 0>, @success=false>
 
 # Note:
 # ----
 # Any Exception instance which is wrapped by
-# the Failure() method will receive `:exception` instead of the `:error` type.
+# the Failure(result: *) method will receive `:exception` instead of the `:error` type.
 ```
 
 [⬆️ Back to Top](#table-of-contents-)
 
 #### How to define custom result types?
 
-Answer: Use a symbol as the argument of `Success()`, `Failure()` methods and declare a block to set their values.
+Answer: Use a symbol as the argument of `Success()`, `Failure()` methods and declare the `result:` keyword to set the result data.
 
 ```ruby
 class Multiply < Micro::Case
  attributes :a, :b
 
  def call!
- return Success(a * b) if a.is_a?(Numeric) && b.is_a?(Numeric)
-
- Failure(:invalid_data) do
- attributes.reject { |_, input| input.is_a?(Numeric) }
+ if a.is_a?(Numeric) && b.is_a?(Numeric)
+ Success result: { number: a * b }
+ else
+ Failure :invalid_data, result: {
+ attributes: attributes.reject { |_, input| input.is_a?(Numeric) }
+ }
  end
  end
 end
@@ -242,39 +250,41 @@ end
 result = Multiply.call(a: 3, b: 2)
 
 result.type # :ok
-result.value # 6
+result.data  # { number: 6 }
 result.success? # true
 
 # Failure result
 
 bad_result = Multiply.call(a: 3, b: '2')
 
 bad_result.type # :invalid_data
-bad_result.value # {"b"=>"2"}
+bad_result.data  # { attributes: {"b"=>"2"} }
 bad_result.failure? # true
 ```
 
 [⬆️ Back to Top](#table-of-contents-)
 
 #### Is it possible to define a custom result type without a block?
 
-Answer: Yes, it is. But only for failure results!
+Answer: Yes, it is possible. But this will have special behavior because the result data will be a hash with the given type as the key and true as its value.
 
 ```ruby
 class Multiply < Micro::Case
  attributes :a, :b
 
  def call!
- return Failure(:invalid_data) unless a.is_a?(Numeric) && b.is_a?(Numeric)
-
- Success(a * b)
+ if a.is_a?(Numeric) && b.is_a?(Numeric)
+ Success result: { number: a * b }
+ else
+ Failure(:invalid_data)
+ end
  end
 end
 
 result = Multiply.call(a: 2, b: '2')
 
 result.failure? # true
-result.value # :invalid_data
+result.data  # { :invalid_data => true }
 result.type # :invalid_data
 result.use_case.attributes # {"a"=>2, "b"=>"2"}