u-service 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 020c6ab3c508004af1b58aa443ed52b67ec587fbc23ce11c4c410dd2806af3cc
-  data.tar.gz: 4b528fe880ce14dadf398a1491cd9ae7b36a6a08a1d4a8cf0e8d9de48f6a0bf8
+  metadata.gz: f637ed45a67693473bf30661b6a4822f1d6ea15246d46b24df3051546781a16b
+  data.tar.gz: ec7c4d4c8052ff1f293b9323bdb447505880dd658a1d0e6219dd2233a40a2b1a
 SHA512:
-  metadata.gz: 1ece16f4c64119f8485ebbf1dbfe23f82c3a7cda4bd4e60da2f92fb0992d192ecf59383a5d8624f8d0fd125dd4c7e88f37ffebab51182c366bc29fac6e85f40f
-  data.tar.gz: 16abd91aa04f7db43b9ff21e2f0ed8d2cb6fdeb6605d6356cd24cadc4feba78090f7236533b5572923e2ae5b186827216f496bdeda7353edc68554aed4bae82a
+  metadata.gz: 5339646f0ce88b4842c9f8d0425ddb16c5edacb81f97dea46eb695da625a2b142fb24a15bf7256f16952f5fb45526c0d812ab8e7a54ac045ce49959ff5a1b637
+  data.tar.gz: 1927b9f7da2f9a5ca5ea369c768173485ff704e3fb8142eccaa612484e6c83a9aeba7589c11f61d573ed7a0b341ba437003f5e9e57bb74eb76ef5789fde84169

data/README.md

@@ -23,6 +23,7 @@ The main goals of this project are:
     - [What is a strict Service Object?](#what-is-a-strict-service-object)
     - [How to validate Service Object attributes?](#how-to-validate-service-object-attributes)
     - [It's possible to compose pipelines with other pipelines?](#its-possible-to-compose-pipelines-with-other-pipelines)
+  - [Examples](#examples)
   - [Comparisons](#comparisons)
   - [Benchmarks](#benchmarks)
   - [Development](#development)
@@ -110,7 +111,7 @@ class Double < Micro::Service::Base
     return Failure(:invalid) { 'the number must be a numeric value' } unless number.is_a?(Numeric)
     return Failure(:lte_zero) { 'the number must be greater than 0' } if number <= 0
 
-    Success(number * number)
+    Success(number * 2)
   end
 end
 
@@ -125,7 +126,7 @@ Double
   .on_failure(:lte_zero) { |msg| raise ArgumentError, msg }
 
 # The output when is a success:
-# 9
+# 6
 
 #=============================#
 # Raising an error if failure #
@@ -251,8 +252,8 @@ Note: To do this your application must have the [activemodel >= 3.2](https://rub
 # any kind of service attribute can be validated.
 #
 class Multiply < Micro::Service::Base
-  attribute :a
-  attribute :b
+  attributes :a, :b
+
   validates :a, :b, presence: true, numericality: true
 
   def call!
@@ -266,13 +267,18 @@ end
 # But if do you want an automatic way to fail
 # your services if there is some invalid data.
 # You can use:
-require 'micro/service/with_validation'
+
+# In some file. e.g: A Rails initializer
+require 'micro/service/with_validation' # or require 'u-service/with_validation'
+
+# In the Gemfile
+gem 'u-service', '~> 0.12.0', require: 'u-service/with_validation'
 
 # Using this approach, you can rewrite the previous sample with fewer lines of code.
 
-class Multiply < Micro::Service::WithValidation
-  attribute :a
-  attribute :b
+class Multiply < Micro::Service::Base
+  attributes :a, :b
+
   validates :a, :b, presence: true, numericality: true
 
   def call!
@@ -281,8 +287,8 @@ class Multiply < Micro::Service::WithValidation
 end
 
 # Note:
-# There is a strict variation for Micro::Service::WithValidation
-# Use Micro::Service::Strict::Validation if do you want this behavior.
+# After requiring the validation mode, the
+# Micro::Service::Strict classes will inherit this new behavior.
 ```
 
 ### It's possible to compose pipelines with other pipelines?
@@ -333,20 +339,30 @@ DoubleAllNumbers = Steps::ConvertToNumbers >> Steps::Double
 SquareAllNumbers = Steps::ConvertToNumbers >> Steps::Square
 DoubleAllNumbersAndAdd2 = DoubleAllNumbers >> Steps::Add2
 SquareAllNumbersAndAdd2 = SquareAllNumbers >> Steps::Add2
-DoubleAllNumbersAndSquareThem = DoubleAllNumbers >> SquareAllNumbersAndAdd2
-SquareAllNumbersAndDoubleThem = SquareAllNumbersAndAdd2 >> DoubleAllNumbers
+SquareAllNumbersAndDouble = SquareAllNumbersAndAdd2 >> DoubleAllNumbers
+DoubleAllNumbersAndSquareAndAdd2 = DoubleAllNumbers >> SquareAllNumbersAndAdd2
 
-DoubleAllNumbersAndSquareThem
+SquareAllNumbersAndDouble
   .call(numbers: %w[1 1 2 2 3 4])
-  .on_success { |value| p value[:numbers] } # [6, 6, 18, 18, 38, 66]
+  .on_success { |value| p value[:numbers] } # [6, 6, 12, 12, 22, 36]
 
-SquareAllNumbersAndDoubleThem
+DoubleAllNumbersAndSquareAndAdd2
   .call(numbers: %w[1 1 2 2 3 4])
-  .on_success { |value| p value[:numbers] } # [6, 6, 12, 12, 22, 36]
+  .on_success { |value| p value[:numbers] } # [6, 6, 18, 18, 38, 66]
 ```
 
 Note: You can blend any of the [syntaxes/approaches to create the pipelines](#how-to-create-a-pipeline-of-service-objects)) - [examples](https://github.com/serradura/u-service/blob/master/test/micro/service/pipeline/blend_test.rb#L7-L34).
 
+## Examples
+
+1. [Rescuing an exception inside of service objects](https://github.com/serradura/u-service/blob/master/examples/rescuing_exceptions.rb)
+2. [Users creation](https://github.com/serradura/u-service/blob/master/examples/users_creation.rb)
+
+    An example of how to use services pipelines to sanitize and validate the input data, and how to represents a common use case, like: create an user.
+3. [CLI calculator](https://github.com/serradura/u-service/tree/master/examples/calculator)
+
+    A more complex example which use rake tasks to demonstrate how to handle user data, and how to use different failures type to control the app flow.
+
 ## Comparisons
 
 Check it out implementations of the same use case with different libs (abstractions).
@@ -360,6 +376,7 @@ Check it out implementations of the same use case with different libs (abstracti
 
 https://github.com/serradura/u-service/tree/master/benchmarks/interactor
 
+![interactor VS u-service](https://github.com/serradura/u-service/blob/master/assets/u-service_benchmarks.png?raw=true)
 
 ## Development
 

data/benchmarks/interactor/pipeline_failure.rb

@@ -5,11 +5,43 @@ gemfile do
 
   gem 'benchmark-ips', '~> 2.7', '>= 2.7.2'
   gem 'interactor', '~> 3.1', '>= 3.1.1'
-  gem 'u-service', '~> 0.11.0'
+  gem 'u-service', '~> 0.12.0'
 end
 
 require 'benchmark/ips'
 
+module IT
+  class ConvertToNumbers
+    include Interactor
+
+    def call
+      numbers = context.numbers
+
+      if numbers.all? { |value| String(value) =~ /\d+/ }
+        context.numbers = numbers.map(&:to_i)
+      else
+        context.fail! numbers: 'must contain only numeric types'
+      end
+    end
+  end
+
+  class Add2
+    include Interactor
+
+    def call
+      numbers = context.numbers
+
+      context.numbers = numbers.map { |number| number + 2 }
+    end
+  end
+
+  class Add2ToAllNumbers
+    include Interactor::Organizer
+
+    organize ConvertToNumbers, Add2
+  end
+end
+
 module MSB
   class ConvertToNumbers < Micro::Service::Base
     attribute :numbers
@@ -58,38 +90,6 @@ module MSS
   Add2ToAllNumbers = ConvertToNumbers >> Add2
 end
 
-module IT
-  class ConvertToNumbers
-    include Interactor
-
-    def call
-      numbers = context.numbers
-
-      if numbers.all? { |value| String(value) =~ /\d+/ }
-        context.numbers = numbers.map(&:to_i)
-      else
-        context.fail! numbers: 'must contain only numeric types'
-      end
-    end
-  end
-
-  class Add2
-    include Interactor
-
-    def call
-      numbers = context.numbers
-
-      context.numbers = numbers.map { |number| number + 2 }
-    end
-  end
-
-  class Add2ToAllNumbers
-    include Interactor::Organizer
-
-    organize ConvertToNumbers, Add2
-  end
-end
-
 NUMBERS = {numbers: %w[1 1 2 2 c 4]}
 
 Benchmark.ips do |x|
@@ -98,6 +98,10 @@ Benchmark.ips do |x|
   x.time = 5
   x.warmup = 2
 
+  x.report('Interactor::Organizer') do
+    IT::Add2ToAllNumbers.call(NUMBERS)
+  end
+
   x.report('Pipeline of Micro::Service::Base') do
     MSB::Add2ToAllNumbers.call(NUMBERS)
   end
@@ -106,29 +110,25 @@ Benchmark.ips do |x|
     MSS::Add2ToAllNumbers.call(NUMBERS)
   end
 
-  x.report('Interactor::Organizer') do
-    IT::Add2ToAllNumbers.call(NUMBERS)
-  end
-
   x.compare!
 end
 
 # Warming up --------------------------------------
+# Interactor::Organizer
+#                          2.355k i/100ms
 # Pipeline of Micro::Service::Base
-#                          5.437k i/100ms
+#                         15.483k i/100ms
 # Pipeline of Micro::Service::Strict
-#                          5.192k i/100ms
-# Interactor::Organizer
-#                          2.236k i/100ms
+#                         13.467k i/100ms
 # Calculating -------------------------------------
+# Interactor::Organizer
+#                          23.767k (± 2.1%) i/s -    120.105k in   5.055726s
 # Pipeline of Micro::Service::Base
-#                          56.665k (± 1.9%) i/s -    288.161k in   5.087185s
+#                         166.013k (± 1.8%) i/s -    836.082k in   5.037938s
 # Pipeline of Micro::Service::Strict
-#                          52.914k (± 2.0%) i/s -    264.792k in   5.006157s
-# Interactor::Organizer
-#                          22.940k (± 2.9%) i/s -    116.272k in   5.072931s
+#                         141.545k (± 2.1%) i/s -    713.751k in   5.044932s
 
 # Comparison:
-# Pipeline of Micro::Service::Base:   56665.3 i/s
-# Pipeline of Micro::Service::Strict: 52914.3 i/s - 1.07x  slower
-# Interactor::Organizer:              22940.3 i/s - 2.47x  slower
+# Pipeline of Micro::Service::Base:   166013.1 i/s
+# Pipeline of Micro::Service::Strict: 141545.4 i/s - 1.17x  slower
+# Interactor::Organizer:              23766.6 i/s - 6.99x  slower

data/benchmarks/interactor/pipeline_success.rb

@@ -5,11 +5,43 @@ gemfile do
 
   gem 'benchmark-ips', '~> 2.7', '>= 2.7.2'
   gem 'interactor', '~> 3.1', '>= 3.1.1'
-  gem 'u-service', '~> 0.11.0'
+  gem 'u-service', '~> 0.12.0'
 end
 
 require 'benchmark/ips'
 
+module IT
+  class ConvertToNumbers
+    include Interactor
+
+    def call
+      numbers = context.numbers
+
+      if numbers.all? { |value| String(value) =~ /\d+/ }
+        context.numbers = numbers.map(&:to_i)
+      else
+        context.fail! numbers: 'must contain only numeric types'
+      end
+    end
+  end
+
+  class Add2
+    include Interactor
+
+    def call
+      numbers = context.numbers
+
+      context.numbers = numbers.map { |number| number + 2 }
+    end
+  end
+
+  class Add2ToAllNumbers
+    include Interactor::Organizer
+
+    organize ConvertToNumbers, Add2
+  end
+end
+
 module MSB
   class ConvertToNumbers < Micro::Service::Base
     attribute :numbers
@@ -58,38 +90,6 @@ module MSS
   Add2ToAllNumbers = ConvertToNumbers >> Add2
 end
 
-module IT
-  class ConvertToNumbers
-    include Interactor
-
-    def call
-      numbers = context.numbers
-
-      if numbers.all? { |value| String(value) =~ /\d+/ }
-        context.numbers = numbers.map(&:to_i)
-      else
-        context.fail! numbers: 'must contain only numeric types'
-      end
-    end
-  end
-
-  class Add2
-    include Interactor
-
-    def call
-      numbers = context.numbers
-
-      context.numbers = numbers.map { |number| number + 2 }
-    end
-  end
-
-  class Add2ToAllNumbers
-    include Interactor::Organizer
-
-    organize ConvertToNumbers, Add2
-  end
-end
-
 NUMBERS = {numbers: %w[1 1 2 2 3 4]}
 
 Benchmark.ips do |x|
@@ -98,6 +98,10 @@ Benchmark.ips do |x|
   x.time = 5
   x.warmup = 2
 
+  x.report('Interactor::Organizer') do
+    IT::Add2ToAllNumbers.call(NUMBERS)
+  end
+
   x.report('Pipeline of Micro::Service::Base') do
     MSB::Add2ToAllNumbers.call(NUMBERS)
   end
@@ -106,29 +110,25 @@ Benchmark.ips do |x|
     MSS::Add2ToAllNumbers.call(NUMBERS)
   end
 
-  x.report('Interactor::Organizer') do
-    IT::Add2ToAllNumbers.call(NUMBERS)
-  end
-
   x.compare!
 end
 
 # Warming up --------------------------------------
+# Interactor::Organizer
+#                          5.047k i/100ms
 # Pipeline of Micro::Service::Base
-#                          3.578k i/100ms
+#                          8.069k i/100ms
 # Pipeline of Micro::Service::Strict
-#                          3.177k i/100ms
-# Interactor::Organizer
-#                          4.695k i/100ms
+#                          6.706k i/100ms
 # Calculating -------------------------------------
+# Interactor::Organizer
+#                          50.656k (± 2.4%) i/s -    257.397k in   5.084184s
 # Pipeline of Micro::Service::Base
-#                          36.087k (± 6.9%) i/s -    182.478k in   5.084835s
+#                          83.309k (± 1.5%) i/s -    419.588k in   5.037749s
 # Pipeline of Micro::Service::Strict
-#                          31.329k (± 6.7%) i/s -    158.850k in   5.094012s
-# Interactor::Organizer
-#                          46.294k (± 6.6%) i/s -    234.750k in   5.093117s
+#                          69.195k (± 1.7%) i/s -    348.712k in   5.041089s
 
 # Comparison:
-# Interactor::Organizer:              46293.6 i/s
-# Pipeline of Micro::Service::Base:   36086.5 i/s - 1.28x  slower
-# Pipeline of Micro::Service::Strict: 31328.5 i/s - 1.48x  slower
+# Pipeline of Micro::Service::Base:   83309.3 i/s
+# Pipeline of Micro::Service::Strict: 69195.1 i/s - 1.20x  slower
+# Interactor::Organizer:              50656.5 i/s - 1.64x  slower

data/benchmarks/interactor/service_failure.rb

@@ -5,24 +5,27 @@ gemfile do
 
   gem 'benchmark-ips', '~> 2.7', '>= 2.7.2'
   gem 'interactor', '~> 3.1', '>= 3.1.1'
-  gem 'u-service', '~> 0.11.0'
+  gem 'u-service', '~> 0.12.0'
 end
 
 require 'benchmark/ips'
 
-class MSB_Multiply < Micro::Service::Base
-  attributes :a, :b
+class IT_Multiply
+  include Interactor
+
+  def call
+    a = context.a
+    b = context.b
 
-  def call!
     if a.is_a?(Numeric) && b.is_a?(Numeric)
-      Success(a * b)
+      context.number = a * b
     else
-      Failure(:invalid_data)
+      context.fail!(type: :invalid_data)
     end
   end
 end
 
-class MSS_Multiply < Micro::Service::Strict
+class MSB_Multiply < Micro::Service::Base
   attributes :a, :b
 
   def call!
@@ -34,17 +37,14 @@ class MSS_Multiply < Micro::Service::Strict
   end
 end
 
-class IT_Multiply
-  include Interactor
-
-  def call
-    a = context.a
-    b = context.b
+class MSS_Multiply < Micro::Service::Strict
+  attributes :a, :b
 
+  def call!
     if a.is_a?(Numeric) && b.is_a?(Numeric)
-      context.number = a * b
+      Success(a * b)
     else
-      context.fail!(type: :invalid_data)
+      Failure(:invalid_data)
     end
   end
 end
@@ -58,6 +58,11 @@ Benchmark.ips do |x|
   x.time = 5
   x.warmup = 2
 
+  x.report('Interactor') do
+    IT_Multiply.call(SYMBOL_KEYS)
+    IT_Multiply.call(STRING_KEYS)
+  end
+
   x.report('Micro::Service::Base') do
     MSB_Multiply.call(SYMBOL_KEYS)
     MSB_Multiply.call(STRING_KEYS)
@@ -68,26 +73,21 @@ Benchmark.ips do |x|
     MSS_Multiply.call(STRING_KEYS)
   end
 
-  x.report('Interactor') do
-    IT_Multiply.call(SYMBOL_KEYS)
-    IT_Multiply.call(STRING_KEYS)
-  end
-
   x.compare!
 end
 
 # Warming up --------------------------------------
-# Micro::Service::Base     5.304k i/100ms
-# Micro::Service::Strict
-#                          4.516k i/100ms
 #           Interactor     1.507k i/100ms
+# Micro::Service::Base    12.902k i/100ms
+# Micro::Service::Strict
+#                          9.758k i/100ms
 # Calculating -------------------------------------
-# Micro::Service::Base     54.444k (± 2.8%) i/s -    275.808k in   5.070215s
+#           Interactor     15.482k (± 2.6%) i/s -     78.364k in   5.065166s
+# Micro::Service::Base    134.861k (± 1.3%) i/s -    683.806k in   5.071263s
 # Micro::Service::Strict
-#                          45.996k (± 1.8%) i/s -    230.316k in   5.008931s
-#           Interactor     15.363k (± 2.2%) i/s -     76.857k in   5.005209s
+#                         101.331k (± 1.5%) i/s -    507.416k in   5.008688s
 
 # Comparison:
-# Micro::Service::Base:    54444.5 i/s
-# Micro::Service::Strict:  45995.8 i/s - 1.18x  slower
-#             Interactor:  15363.0 i/s - 3.54x  slower
+# Micro::Service::Base:   134861.1 i/s
+# Micro::Service::Strict: 101331.5 i/s - 1.33x  slower
+#           Interactor:   15482.0 i/s - 8.71x  slower

data/benchmarks/interactor/service_success.rb

@@ -5,24 +5,27 @@ gemfile do
 
   gem 'benchmark-ips', '~> 2.7', '>= 2.7.2'
   gem 'interactor', '~> 3.1', '>= 3.1.1'
-  gem 'u-service', '~> 0.11.0'
+  gem 'u-service', '~> 0.12.0'
 end
 
 require 'benchmark/ips'
 
-class MSB_Multiply < Micro::Service::Base
-  attributes :a, :b
+class IT_Multiply
+  include Interactor
+
+  def call
+    a = context.a
+    b = context.b
 
-  def call!
     if a.is_a?(Numeric) && b.is_a?(Numeric)
-      Success(a * b)
+      context.number = a * b
     else
-      Failure(:invalid_data)
+      context.fail!(:invalid_data)
     end
   end
 end
 
-class MSS_Multiply < Micro::Service::Strict
+class MSB_Multiply < Micro::Service::Base
   attributes :a, :b
 
   def call!
@@ -34,17 +37,14 @@ class MSS_Multiply < Micro::Service::Strict
   end
 end
 
-class IT_Multiply
-  include Interactor
-
-  def call
-    a = context.a
-    b = context.b
+class MSS_Multiply < Micro::Service::Strict
+  attributes :a, :b
 
+  def call!
     if a.is_a?(Numeric) && b.is_a?(Numeric)
-      context.number = a * b
+      Success(a * b)
     else
-      context.fail!(:invalid_data)
+      Failure(:invalid_data)
     end
   end
 end
@@ -58,6 +58,11 @@ Benchmark.ips do |x|
   x.time = 5
   x.warmup = 2
 
+  x.report('Interactor') do
+    IT_Multiply.call(SYMBOL_KEYS)
+    IT_Multiply.call(STRING_KEYS)
+  end
+
   x.report('Micro::Service::Base') do
     MSB_Multiply.call(SYMBOL_KEYS)
     MSB_Multiply.call(STRING_KEYS)
@@ -68,26 +73,21 @@ Benchmark.ips do |x|
     MSS_Multiply.call(STRING_KEYS)
   end
 
-  x.report('Interactor') do
-    IT_Multiply.call(SYMBOL_KEYS)
-    IT_Multiply.call(STRING_KEYS)
-  end
-
   x.compare!
 end
 
 # Warming up --------------------------------------
-# Micro::Service::Base     5.365k i/100ms
+#           Interactor     2.943k i/100ms
+# Micro::Service::Base    12.540k i/100ms
 # Micro::Service::Strict
-#                          4.535k i/100ms
-#           Interactor     2.620k i/100ms
+#                          9.584k i/100ms
 # Calculating -------------------------------------
-# Micro::Service::Base     51.795k (± 4.7%) i/s -    262.885k in   5.086671s
+#           Interactor     29.874k (± 2.7%) i/s -    150.093k in   5.027909s
+# Micro::Service::Base    131.440k (± 1.9%) i/s -    664.620k in   5.058327s
 # Micro::Service::Strict
-#                          46.253k (± 1.6%) i/s -    231.285k in   5.001748s
-#           Interactor     29.561k (± 3.3%) i/s -    149.340k in   5.057720s
+#                          99.111k (± 2.2%) i/s -    498.368k in   5.031006s
 
 # Comparison:
-# Micro::Service::Base:    51794.5 i/s
-# Micro::Service::Strict:  46253.0 i/s - 1.12x  slower
-#             Interactor:  29561.5 i/s - 1.75x  slower
+# Micro::Service::Base:   131440.3 i/s
+# Micro::Service::Strict: 99111.3 i/s - 1.33x  slower
+#           Interactor:   29873.6 i/s - 4.40x  slower

data/examples/calculator/README.md

@@ -0,0 +1,56 @@
+# μ-service - Calculator example
+
+This example uses [rake](http://rubygems.org/gems/rake) to expose a CLI calculator.
+
+## Installation instructions
+```sh
+gem install rake
+gem install u-service -v 0.12.0
+```
+
+### Usage
+
+![gif](https://github.com/serradura/u-service/blob/master/examples/calculator/assets/usage.gif?raw=true)
+
+#### Listing the available rake tasks
+```sh
+rake -T
+
+# rake calc:add[a,b]       # adds two numbers
+# rake calc:divide[a,b]    # divides two numbers
+# rake calc:multiply[a,b]  # multiplies two numbers
+# rake calc:subtract[a,b]  # subtracts two numbers
+```
+
+#### Calculating integer numbers
+```sh
+rake calc:add[3,2]
+# 3 + 2 = 5
+
+rake calc:subtract[3,2]
+# 3 - 2 = 1
+
+rake calc:multiply[3,2]
+# 3 x 2 = 6
+
+rake calc:divide[3,2]
+# 3 / 2 = 1
+```
+
+#### Calculating float numbers
+```sh
+rake calc:divide[3.0,2.0]
+# 3.0 / 2.0 = 1.5
+
+rake calc:divide[-3.0,2.0]
+# -3.0 / 2.0 = -1.5
+```
+
+#### Calculation errors
+```sh
+rake calc:add[1,a]
+# ERROR: The arguments must contain only numeric values
+
+rake calc:add[-\ 1,2]
+# ERROR: Arguments can't have spaces: a: "- 1", b: "2"
+```

data/examples/calculator/Rakefile

@@ -0,0 +1,60 @@
+require 'u-service'
+
+require_relative 'calc/operation'
+require_relative 'calc/normalize_args'
+require_relative 'calc/transform_into_numbers'
+
+module Calc
+  TransformArgsIntoNumbers = NormalizeArgs >> TransformIntoNumbers
+
+  module With
+    Add = TransformArgsIntoNumbers >> Operation::Add
+    Divide = TransformArgsIntoNumbers >> Operation::Divide
+    Subtract = TransformArgsIntoNumbers >> Operation::Subtract
+    Multiply = TransformArgsIntoNumbers >> Operation::Multiply
+  end
+end
+
+class PerformTask < Micro::Service::Base
+  attributes :args, :operation
+
+  def call!
+    operation
+      .call(args: args)
+      .on_success { |value| print_operation(value) }
+      .on_failure(:not_a_number) { |message| puts "ERROR: #{message}" }
+      .on_failure(:arguments_with_space_chars) do |(a, b)|
+        puts "ERROR: Arguments can't have spaces: a: #{a}, b: #{b}"
+      end
+  end
+
+  private def print_operation(a:, operator:, b:, result:)
+    puts "#{a} #{operator} #{b} = #{result}"
+  end
+end
+
+namespace :calc do
+  desc 'adds two numbers'
+  task :add, [:a, :b] do |_task, args|
+    PerformTask.call(args: args, operation: Calc::With::Add)
+  end
+
+  desc 'divides two numbers'
+  task :divide, [:a, :b] do |_task, args|
+    begin
+      PerformTask.call(args: args, operation: Calc::With::Divide)
+    rescue ZeroDivisionError => e
+      puts "ERROR: #{e.message}"
+    end
+  end
+
+  desc 'subtracts two numbers'
+  task :subtract, [:a, :b] do |_task, args|
+    PerformTask.call(args: args, operation: Calc::With::Subtract)
+  end
+
+  desc 'multiplies two numbers'
+  task :multiply, [:a, :b] do |_task, args|
+    PerformTask.call(args: args, operation: Calc::With::Multiply)
+  end
+end

data/examples/calculator/calc/normalize_args.rb

@@ -0,0 +1,17 @@
+module Calc
+  class NormalizeArgs < Micro::Service::Base
+    attributes :args
+
+    def call!
+      a, b = normalize(args[:a]), normalize(args[:b])
+
+      return Success(a: a, b: b) if a !~ /\s/ && b !~ /\s/
+
+      Failure(:arguments_with_space_chars) { [a.inspect, b.inspect] }
+    end
+
+    private def normalize(value)
+      String(value).strip
+    end
+  end
+end

data/examples/calculator/calc/operation.rb

@@ -0,0 +1,39 @@
+class Operation < Micro::Service::Base
+  attributes :a, :b
+
+  private def result_of(operation_result)
+    attributes(:a, :operator, :b).merge(result: operation_result)
+  end
+
+  class Add < Operation
+    attribute :operator, '+'
+
+    def call!
+      Success(result_of(a + b))
+    end
+  end
+
+  class Subtract < Operation
+    attribute :operator, '-'
+
+    def call!
+      Success(result_of(a - b))
+    end
+  end
+
+  class Multiply < Operation
+    attribute :operator, 'x'
+
+    def call!
+      Success(result_of(a * b))
+    end
+  end
+
+  class Divide < Operation
+    attribute :operator, '/'
+
+    def call!
+      Success(result_of(a / b))
+    end
+  end
+end

data/examples/calculator/calc/transform_into_numbers.rb

@@ -0,0 +1,18 @@
+class TransformIntoNumbers < Micro::Service::Base
+  attributes :a, :b
+
+  def call!
+    number_a, number_b = number(a), number(b)
+
+    if number_a && number_b
+      Success(a: number(a), b: number(b))
+    else
+      Failure(:not_a_number) { 'The arguments must contain only numeric values' }
+    end
+  end
+
+  private def number(value)
+    return value.to_i if value =~ /\A[\-,=]?\d+\z/
+    return value.to_f if value =~ /\A[\-,=]?\d+\.\d+\z/
+  end
+end

data/examples/rescuing_exceptions.rb

@@ -0,0 +1,53 @@
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+
+  gem 'u-service', '~> 0.12.0'
+end
+
+class Divide < Micro::Service::Base
+  attributes :a, :b
+
+  def call!
+    return Failure('numbers must be greater than 0') if a < 0 || b < 0
+
+    Success(a / b)
+  rescue => e
+    Failure(e.message)
+  end
+end
+
+#---------------------------------#
+puts "\n-- Success scenario --\n\n"
+#---------------------------------#
+
+result = Divide.call(a: 4, b: 2)
+
+puts result.value if result.success?
+
+#----------------------------------#
+puts "\n-- Failure scenarios --\n\n"
+#----------------------------------#
+
+result = Divide.call(a: 4, b: 0)
+
+puts result.value if result.failure?
+
+puts ''
+
+result = Divide.call(a: -4, b: 2)
+
+puts result.value if result.failure?
+
+# :: example of the output: ::
+
+# -- Success scenario --
+#
+# 2
+#
+# -- Failure scenarios --
+#
+# divided by 0
+#
+# numbers must be greater than 0

data/examples/users_creation.rb

@@ -0,0 +1,133 @@
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+
+  # NOTE: I used an older version of the Activemodel only to show the compatibility with its older versions.
+  gem 'activemodel', '~> 3.2', '>= 3.2.22.5'
+  gem 'u-service', '~> 0.12.0'
+end
+
+require 'micro/service/with_validation'
+
+module Users
+  class Entity
+    include Micro::Attributes.with(:initialize)
+
+    attributes :id, :name, :email
+
+    def persisted?
+      !id.nil?
+    end
+  end
+
+  module Creation
+    require 'uri'
+    require 'securerandom'
+
+    class ProcessParams < Micro::Service::Base
+      attributes :name, :email
+
+      def call!
+        Success(name: normalized_name, email: String(email).downcase.strip)
+      end
+
+      private def normalized_name
+        String(name).strip.gsub(/\s+/, ' ')
+      end
+    end
+
+    class ValidateParams < Micro::Service::WithValidation
+      attributes :name, :email
+
+      validates :name, presence: true
+      validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+
+      def call!
+        Success(attributes(:name, :email))
+      end
+    end
+
+    class Persist < Micro::Service::Base
+      attributes :name, :email
+
+      def call!
+        Success(user: Entity.new(user_data))
+      end
+
+      private def user_data
+        attributes.merge(id: SecureRandom.uuid)
+      end
+    end
+
+    class SendToCRM < Micro::Service::Base
+      attribute :user
+
+      def call!
+        return Success(user_id: user.id, crm_id: send_to_crm) if user.persisted?
+
+        Failure(:crm_error) { 'User can\'t be sent to the CRM' }
+      end
+
+      private def send_to_crm
+        # Do some integration stuff...
+        SecureRandom.uuid
+      end
+    end
+
+    Process = ProcessParams >> ValidateParams >> Persist >> SendToCRM
+  end
+end
+
+require 'pp'
+
+params = {
+  "name" => "  Rodrigo  \n  Serradura ",
+  "email" => "   RoDRIGo.SERRAdura@gmail.com   "
+}
+
+#--------------------------------------#
+puts "\n-- Parameters processing --\n\n"
+#--------------------------------------#
+
+print 'Before: '
+p params
+
+print ' After: '
+Users::Creation::ProcessParams.call(params).on_success { |value| p value }
+
+#---------------------------------#
+puts "\n-- Success scenario --\n\n"
+#---------------------------------#
+
+Users::Creation::Process
+  .call(params)
+  .on_success do |user_id:, crm_id:|
+    puts " CRM ID: #{crm_id}"
+    puts "USER ID: #{user_id}"
+  end
+
+#---------------------------------#
+puts "\n-- Failure scenario --\n\n"
+#---------------------------------#
+
+Users::Creation::Process
+  .call(name: '', email: '')
+  .on_failure { |errors:| p errors.full_messages }
+
+
+# :: example of the output: ::
+
+# -- Parameters processing --
+#
+# Before: {"name"=>"  Rodrigo  \n  Serradura ", "email"=>"   RoDRIGo.SERRAdura@gmail.com   "}
+#  After: {:name=>"Rodrigo Serradura", :email=>"rodrigo.serradura@gmail.com"}
+#
+# -- Success scenario --
+#
+#  CRM ID: f3f189f6-ba6a-40ab-998c-c86773c41c83
+# USER ID: c140ffc3-6a7c-4554-972a-c2a0d59f8cb1
+#
+# -- Failure scenarios --
+#
+# ["Name can't be blank", "Email is invalid"]

data/lib/micro/service/base.rb

@@ -5,11 +5,11 @@ module Micro
     class Base
       include Micro::Attributes.without(:strict_initialize)
 
-      INVALID_RESULT = '#call! must return a Micro::Service::Result instance'.freeze
-
+      UNEXPECTED_RESULT = '#call! must return a Micro::Service::Result instance'.freeze
+      InvalidResultInstance = ArgumentError.new('argument must be an instance of Micro::Service::Result'.freeze)
       ResultIsAlreadyDefined = ArgumentError.new('result is already defined'.freeze)
 
-      private_constant :INVALID_RESULT, :ResultIsAlreadyDefined
+      private_constant :UNEXPECTED_RESULT, :ResultIsAlreadyDefined, :InvalidResultInstance
 
       def self.>>(service)
         Micro::Service::Pipeline[self, service]
@@ -31,29 +31,34 @@ module Micro
       end
 
       def call
-        result = call!
-        return result if result.is_a?(Service::Result)
-        raise TypeError, self.class.name + INVALID_RESULT
+        __call
       end
 
       def __set_result__(result)
+        raise InvalidResultInstance unless result.is_a?(Result)
         raise ResultIsAlreadyDefined if @__result
         @__result = result
       end
 
       private
 
+        def __call
+          result = call!
+          return result if result.is_a?(Service::Result)
+          raise TypeError, self.class.name + UNEXPECTED_RESULT
+        end
+
         def __get_result__
           @__result ||= Result.new
         end
 
-        def Success(arg=nil)
-          value, type = block_given? ? [yield, arg] : [arg, nil]
+        def Success(arg = :ok)
+          block_given? ? (value, type = yield, arg) : (value, type = arg, :ok)
           __get_result__.__set__(true, value, type)
         end
 
-        def Failure(arg=nil)
-          value, type = block_given? ? [yield, arg] : [arg, nil]
+        def Failure(arg = :error)
+          block_given? ? (value, type = yield, arg) : (value, type = arg, :error)
           __get_result__.__set__(false, value, type)
         end
     end

data/lib/micro/service/pipeline.rb

@@ -28,7 +28,7 @@ module Micro
           @services = services
         end
 
-        def call(arg={})
+        def call(arg = {})
           @services.reduce(initial_result(arg)) do |result, service|
             break result if result.failure?
             service.__new__(result, result.value).call
@@ -45,7 +45,7 @@ module Micro
             return arg.call if arg_to_call?(arg)
             return arg if arg.is_a?(Micro::Service::Result)
             result = Micro::Service::Result.new
-            result.__set__(true, arg, nil)
+            result.__set__(true, arg, :ok)
           end
 
           def arg_to_call?(arg)
@@ -64,7 +64,7 @@ module Micro
           @__pipeline = Reducer.build(args)
         end
 
-        def call(options={})
+        def call(options = {})
           new(options).call
         end
       end

data/lib/micro/service/result.rb

@@ -3,12 +3,12 @@
 module Micro
   module Service
     class Result
-      InvalidType = TypeError.new('type must be nil or a symbol'.freeze)
+      InvalidType = TypeError.new('type must be a symbol'.freeze)
 
       attr_reader :value, :type
 
       def __set__(is_success, value, type)
-        raise InvalidType unless type.nil? || type.is_a?(Symbol)
+        raise InvalidType unless type.is_a?(Symbol)
 
         @success, @value, @type = is_success, value, type
 
@@ -23,22 +23,22 @@ module Micro
         !success?
       end
 
-      def on_success(arg=nil)
+      def on_success(arg = :ok)
         self.tap { yield(value) if success_type?(arg) }
       end
 
-      def on_failure(arg=nil)
+      def on_failure(arg = :error)
         self.tap{ yield(value) if failure_type?(arg) }
       end
 
       private
 
         def success_type?(arg)
-          success? && (arg.nil? || arg == type)
+          success? && (arg == :ok || arg == type)
         end
 
         def failure_type?(arg)
-          failure? && (arg.nil? || arg == type)
+          failure? && (arg == :error || arg == type)
         end
     end
   end

data/lib/micro/service/version.rb

@@ -2,6 +2,6 @@
 
 module Micro
   module Service
-    VERSION = '0.12.0'.freeze
+    VERSION = '0.13.0'.freeze
   end
 end

data/lib/micro/service/with_validation.rb

@@ -3,17 +3,15 @@
 require 'micro/service'
 
 module Micro
-  class Service::WithValidation < Micro::Service::Base
-    include Micro::Attributes::Features::ActiveModelValidations
+  module Service
+    class Base
+      include Micro::Attributes::Features::ActiveModelValidations
 
-    def call
-      return Failure(errors: self.errors) unless valid?
+      def call
+        return Failure(:validation_error) { {errors: self.errors, service: self} } unless valid?
 
-      super
+        __call
+      end
     end
   end
-
-  class Service::Strict::Validation < Service::WithValidation
-    include Micro::Attributes::Features::StrictInitialize
-  end
 end

data/lib/u-service/with_validation.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'micro/service/with_validation'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: u-service
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Rodrigo Serradura
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-08-14 00:00:00.000000000 Z
+date: 2019-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: u-attributes
@@ -68,6 +68,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- assets/u-service_benchmarks.png
 - benchmarks/interactor/pipeline_failure.rb
 - benchmarks/interactor/pipeline_success.rb
 - benchmarks/interactor/service_failure.rb
@@ -76,6 +77,14 @@ files:
 - bin/setup
 - comparisons/interactor.rb
 - comparisons/u-service.rb
+- examples/calculator/README.md
+- examples/calculator/Rakefile
+- examples/calculator/assets/usage.gif
+- examples/calculator/calc/normalize_args.rb
+- examples/calculator/calc/operation.rb
+- examples/calculator/calc/transform_into_numbers.rb
+- examples/rescuing_exceptions.rb
+- examples/users_creation.rb
 - lib/micro/service.rb
 - lib/micro/service/base.rb
 - lib/micro/service/pipeline.rb
@@ -84,6 +93,7 @@ files:
 - lib/micro/service/version.rb
 - lib/micro/service/with_validation.rb
 - lib/u-service.rb
+- lib/u-service/with_validation.rb
 - test.sh
 - u-service.gemspec
 homepage: https://github.com/serradura/u-service