u-service 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0a881f3a6544fe98f2384ee40522a44e1fcc2011f60fd1e312d1fbb4afee79f
-  data.tar.gz: 425f39a6977091d5e9303b9fc86f1c261115737bffc693f929f8cb0dafce43bb
+  metadata.gz: a21e14f14ad8d4b658660c94ed2e3687c4b589531a61f11fee63c9fcc0810615
+  data.tar.gz: e504198f717114b9fd6794b795381ebfced5a6e29bda56ad83cc1f055296efc6
 SHA512:
-  metadata.gz: cf65966cfd4ef161f07ff5e97e787afd2afe810420223941a574e1eeb0a236b98f0d83a4c391b374ac53391afaef7f2e23a4abbecf7a0b01adf89b125a3ea08a
-  data.tar.gz: 2c88814614909b674a64ec4c727c5ecaeb2c42e83fae514ee044c085aa0753862529774d872eace7e2106461366d46a9521c94348f8931ce47fa10ab0b6cca4b
+  metadata.gz: 74d66f07259c0d31c1469d70bd9a89190fafce614bdc4adced7e2e8a4dba07859483f020d90a87850804485f44e468835d481263c027fe86e4bbb9eee8af15ff
+  data.tar.gz: c18b4b93cac117a7a5ea48d5bca5ef17811d62eedd18419a75d40ba6559b2518e5d7cb0c745dc38621034c0c8f802f247c602e4e6acb8ea1dee4b1365b5a25bc

data/.tool-versions

@@ -0,0 +1 @@
+ruby 2.6.3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    u-service (0.6.0)
+    u-service (0.7.0)
       u-attributes (~> 1.1)
 
 GEM

data/README.md

@@ -6,9 +6,25 @@
 μ-service (Micro::Service)
 ==========================
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/micro/service`. To experiment with that code, run `bin/console` for an interactive prompt.
+Create simple and powerful service objects.
 
-TODO: Delete this and the text above, and describe your gem
+- [μ-service (Micro::Service)](#%ce%bc-service-microservice)
+  - [Required Ruby version](#required-ruby-version)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [How to create a basic Service Object?](#how-to-create-a-basic-service-object)
+    - [How to use the Service Object result hooks?](#how-to-use-the-service-object-result-hooks)
+    - [How to create a pipeline of Service Objects?](#how-to-create-a-pipeline-of-service-objects)
+    - [What is a strict Service Object?](#what-is-a-strict-service-object)
+    - [How to validate Service Object attributes?](#how-to-validate-service-object-attributes)
+  - [Development](#development)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [Code of Conduct](#code-of-conduct)
+
+## Required Ruby version
+
+> \>= 2.2.0
 
 ## Installation
 
@@ -28,7 +44,203 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### How to create a basic Service Object?
+
+```ruby
+class Multiply < Micro::Service::Base
+  attributes :a, :b
+
+  def call!
+    if a.is_a?(Numeric) && b.is_a?(Numeric)
+      Success(a * b)
+    else
+      Failure(:invalid_data)
+    end
+  end
+end
+
+#====================#
+# Calling a service  #
+#====================#
+
+result = Multiply.call(a: 2, b: 2)
+p result.success? # true
+p result.value    # 4
+
+#----------------------------#
+# Calling a service instance #
+#----------------------------#
+
+result = Multiply.new(a: 2, b: 3).call
+p result.success? # true
+p result.value    # 6
+
+#===========================#
+# Verify the result failure #
+#===========================#
+
+result = Multiply.call(a: '2', b: 2)
+p result.success? # false
+p result.failure? # true
+p result.value    # :invalid_data
+```
+
+### How to use the Service Object result hooks?
+
+```ruby
+class Double < Micro::Service::Base
+  attributes :number
+
+  def call!
+    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)
+  end
+end
+
+#================================#
+# Printing the output if success #
+#================================#
+
+Double
+  .call(number: 3)
+  .on_success { |number| p number }
+  .on_failure(:invalid) { |msg| raise TypeError, msg }
+  .on_failure(:lte_zero) { |msg| raise ArgumentError, msg }
+
+# The output when is a success:
+# 9
+
+#=============================#
+# Raising an error if failure #
+#=============================#
+
+Double
+  .call(number: -1)
+  .on_success { |number| p number }
+  .on_failure(:invalid) { |msg| raise TypeError, msg }
+  .on_failure(:lte_zero) { |msg| raise ArgumentError, msg }
+
+# The output (raised an error) when is a failure:
+# ArgumentError (the number must be greater than 0)
+```
+
+### How to create a pipeline of Service Objects?
+
+```ruby
+module Steps
+  class ConvertToNumbers < Micro::Service::Base
+    attribute :relation
+
+    def call!
+      if relation.all? { |value| String(value) =~ /\d+/ }
+        Success(numbers: relation.map(&:to_i))
+      else
+        Failure('relation must contain only numbers')
+      end
+    end
+  end
+
+  class Add2 < Micro::Service::Strict
+    attribute :numbers
+
+    def call!
+      Success(numbers.map { |number| number + 2 })
+    end
+  end
+
+  class Double < Micro::Service::Strict
+    attribute :numbers
+
+    def call!
+      Success(numbers.map { |number| number * number })
+    end
+  end
+end
+
+Add2ToAllNumbers = Micro::Service::Pipeline[
+  Steps::ConvertToNumbers,
+  Steps::Add2
+]
+
+DoubleAllNumbers = Micro::Service::Pipeline[
+  Steps::ConvertToNumbers,
+  Steps::Double
+]
+
+result = Add2ToAllNumbers.call(relation: %w[1 1 2 2 3 4])
+
+p result.success? # true
+p result.value    # [3, 3, 4, 4, 5, 6]
+
+DoubleAllNumbers
+  .call(relation: %w[1 1 b 2 3 4])
+  .on_failure { |message| p message } # "relation must contain only numbers"
+```
+
+### What is a strict Service Object?
+
+A: Is a service object which will require all keywords (attributes) on its initialization.
+
+```ruby
+class Double < Micro::Service::Strict
+  attribute :numbers
+
+  def call!
+    Success(numbers.map { |number| number * number })
+  end
+end
+
+Double.call({})
+
+# The output (raised an error):
+# ArgumentError (missing keyword: :numbers)
+```
+
+### How to validate Service Object attributes?
+
+Note: To do this your application must have the (activemodel >= 3.2)(https://rubygems.org/gems/activemodel) as a dependency.
+
+```ruby
+#
+# By default, if your project has the activemodel
+# any kind of service attribute can be validated.
+#
+class Multiply < Micro::Service::Base
+  attribute :a
+  attribute :b
+  validates :a, :b, presence: true, numericality: true
+
+  def call!
+    return Success(number: a * b) if valid?
+
+    Failure(errors: self.errors)
+  end
+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'
+
+# Using this approach, you can rewrite the previous sample with fewer lines of code.
+
+class Multiply < Micro::Service::WithValidation
+  attribute :a
+  attribute :b
+  validates :a, :b, presence: true, numericality: true
+
+  def call!
+    Success(number: a * b)
+  end
+end
+
+# Note:
+# There is a strict variation for Micro::Service::WithValidation
+# Use Micro::Service::Strict::Validation if do you want this behavior.
+```
 
 ## Development
 

data/lib/micro/service/pipeline.rb

@@ -2,39 +2,43 @@
 
 module Micro
   module Service
-    class Pipeline
-      INVALID_COLLECTION =
-        'argument must be a collection of `Micro::Service::Base` classes'.freeze
+    module Pipeline
+      class Reducer
+        def initialize(services)
+          @services = services
+        end
 
-      def self.[](*services)
-        new(services)
-      end
+        def call(arg={})
+          @services.reduce(initial_result(arg)) do |result, service|
+            break result if result.failure?
+            service.call(result.value)
+          end
+        end
+
+        private
 
-      def initialize(services)
-        @services = validate!(services)
+          def initial_result(arg)
+            return arg if arg.is_a?(Micro::Service::Result)
+            Micro::Service::Result::Success(value: arg)
+          end
       end
 
-      def call(arg={})
-        @services.reduce(initial_result(arg)) do |result, service|
-          break result if result.failure?
-          service.call(result.value)
-        end
+      private_constant :Reducer
+
+      INVALID_SERVICES =
+        'argument must be a collection of `Micro::Service::Base` classes'.freeze
+
+      def self.[](*args)
+        self.new(args)
       end
 
-      private
+      def self.new(args)
+        services = Array(args)
 
-        def validate!(services)
-          Array(services).tap do |collection|
-            if collection.any? { |klass| !(klass < ::Micro::Service::Base) }
-              raise ArgumentError, INVALID_COLLECTION
-            end
-          end
-        end
+        raise ArgumentError, INVALID_SERVICES if services.any? { |klass| !(klass < ::Micro::Service::Base) }
 
-        def initial_result(arg)
-          return arg if arg.is_a?(Micro::Service::Result)
-          Micro::Service::Result::Success(value: arg)
-        end
+        Reducer.new(services)
+      end
     end
   end
 end

data/lib/micro/service/version.rb

@@ -2,6 +2,6 @@
 
 module Micro
   module Service
-    VERSION = '0.6.0'.freeze
+    VERSION = '0.7.0'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: u-service
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -74,6 +74,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".tool-versions"
 - ".travis.sh"
 - ".travis.yml"
 - CODE_OF_CONDUCT.md