simple_operation 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 32d773cfd369dfe0f15ab8ee90b2f73b66dec5e3
-  data.tar.gz: a20f16a09077c99747b61f99961e937815e637e4
+  metadata.gz: e4d62e3d9a9b251bc5134553b1fed1ed60252528
+  data.tar.gz: 275f05866d4c3cdeb98edf14485258e42e979045
 SHA512:
-  metadata.gz: e2559b6cae03f2b3de34361c604e4cce3b769b20836473471266528be4503462a4f3078284e6eaf2d68fe24396a1332c45dc36ba0c22b34071e99fc245232e40
-  data.tar.gz: 427d88c82e640db9c389249e00be447d844ac525039c971213420b30f2b20324897ce8aacc2a872e2e08339a5f9eb39e39249cd864d6736727a1453966d0a015
+  metadata.gz: 89a3030ad2ed50c1ff4fe4debc67e4638592bb092b5e50ba704ae6f42a6bcea0fa487d64764cb55163052f2f5232944e9be122300fa761e5cec4877b0baf5629
+  data.tar.gz: 177cab278536edc7c62449cbd0a977160cb1d0ecf049ab41b015f5c57561153271f94d8f25e30e98284f2197dce3822947644a0713cf8674b84fe7eb16e75aa5

data/README.md

@@ -18,76 +18,182 @@ Or install it yourself as:
 
     $ gem install simple_operation
 
+## Background
+
+Working with large business applications means working with a big business logic layer.
+There are many Ruby gems that help building business logic layer, notably:
+
+* Trailblazer (http://trailblazer.to)
+* dry-transaction (http://dry-rb.org/gems/dry-transaction/)
+
+Why another gem then? I wanted something very simple and easy to use
+and I wanted to be able to call my services like labmdas, without having to create new objects outside of the service.
+I wanted to achieve syntax like `CreateOrder.(articles, user)` with the flexibility of memoizing objects inside the service.
+
 ## Usage
 
-Example usage for SimpleOperation is creating user:
+### Basic service
 
-```ruby
-class CreateUser < SimpleOperation.new(:login, :password)
+To define a new service, you have to do 2 steps:
+
+1. Create a new class by calling `SimpleOperation.new` with parameters you will be providing to the service
+2. Put your business logic into `call` method.
 
-  InvalidUser = Class.new(RuntimeError)
+Example:
+
+```
+CreateOrder = SimpleOperation.new(:articles, :user) do
 
   def call
-    user = User.new(login, password)
-    raise InvalidUser unless valid_user?(user)
-    UserRepository.persist(user)
-    user
+    order = Order.new(articles_ids: articles.map(&:id), user_is: user.id)
+    OrderRepository.persist(order)
+    order
   end
+end
+```
 
-  private
-    def valid_user?(user)
-      !UserRepository.fetch_all_logins.include?(user.login)
-    end
+or in a more common class definition style:
+
+```
+class CreateOrder < SimpleOperation.new(:articles, :user)
+
+  def call
+    # your business logic here, methods articles and user are available
+  end
 
 end
+```
 
+Then you can call your service in one of two ways. A more functional way:
 
-CreateUser.('Grzegorz', 'arnvald.to@gmail.com')
+```
+CreateOrder.(some_articles, some_user)
+```
 
-# the same effect as line above
-CreateUser.new('Grzegorz', 'arnvald.to@gmail.com').()
+or by instantiating the object first
 
-# `perform` is an alias for `call`
-CreateUser.new('Grzegorz', 'arnvald.to@gmail.com').perform
+```
+CreateOrder.new(some_articles, some_user).()
 ```
 
-If you need output that consists of more than one field, instead of returning multiple values,
-you can use `result` methods:
+### Returning result
 
-```ruby
-class CreateCompanyAndUser < SimpleOperation(:name, :login, :password)
-  # result on class-level defines output structure
-  result :company, :user
+SimpleOperation allows defining results by using success/failure definitions
+
+```
+class CreateUser < SimpleOperation.new(:login, :password)
+  success :user
+  failure :error
 
   def call
-    # result in call method returns defined structure
-    result create_company(name), create_user(login, password)
+    if unique_login?
+      user = User.new(login, hashed_password)
+      UserRepository.persist(user)
+      Success(user)
+    else
+      Failure("login taken")
+    end
+  end
+
+  private
+
+  def hashed_password
+    ...
+  end
+
+  def unique_login?
+    ...
   end
+
 end
 ```
 
-There's a sugar syntax for creating classes:
+Using result definitions allows to easily check for status of the transaction and to define callbacks:
+
+```
+result1 = CreateUser.("grzegorz", "witek")
+
+result1.success? # => true
+result1.user # => instance of User object
+result1.failure? # => false
+
+result2 = CreateUser.("grzegorz", "witek")
+result2.success? # => false
+result2.error # => "login taken"
+result2.failure? # => true
+```
+
+### Result callbacks
+
+Returning success and failure allows using callbacks:
+
+```
+result1
+.on_success { |s| puts "user created with login #{s.user.login}" }
+.on_failure { |f| puts "creation failed because #{f.error}" }
+
+# the code above will print "user created with login grzegorz"
+
+result2
+.on_success { |s| puts "user created with login #{s.user.login}" }
+.on_failure { |f| puts "creation failed because #{f.error}" }
+
+# the code above will print "creation failed because login taken"
+```
+
+Failure callbacks can be assigned to specific reasons, which requires adding `:reason`
+field to the failed response:
+
+```
+class Authenticate < SimpleOperation.new(:login, :password)
+  success :user
+  failure :reason, :message
 
-```ruby
-CreateUser = SimpleOperation.new(:login, :password) do
   def call
-    ...
+    return Failure("NO_USER", "user does not exist") unless login_exists?
+    return Failure("WRONG_PASS", "wrong password") unless valid_password?
+    return Success(user)
   end
 end
 ```
 
-or
+Then each error can be easily handled in a different way:
 
-```ruby
-require 'simple_operation/ext'
+```
+result = Authenticate.(login, password)
+
+result
+.on_failure("NO_USER") { create_new_user(login, password) }
+.on_failure("WRONG_PASS") { increase_invalid_attempt_count }
+.on_failure() { raise DontKnowWhatToDo } # this will be called only if the previous reasons don't match
+.on_success { |s| s.user }
+```
+
+### Generic results
+
+If you don't need a distinction between success and failure, you can define generic result
+
+```
+class AggregateSalesData < SimpleOperation.new(:orders)
+
+  result :average_transaction, :number_of_transactions, :maximum_transaction
 
-CreateUser = SimpleOperation(:login, :password)
   def call
-    ...
+    Result(
+      find_average_transaction,
+      transactions.size,
+      find_max_transaction
+    )
   end
+
 end
-```
 
+result = AggregateSalesData.(orders)
+
+result.average_transaction
+result.number_of_transactions
+result.maximum_transaction
+```
 
 ## Contributing
 

data/lib/simple_operation.rb

@@ -1,4 +1,6 @@
 require_relative './simple_operation/version'
+require_relative './simple_operation/success'
+require_relative './simple_operation/failure'
 
 class SimpleOperation
 
@@ -28,9 +30,29 @@ class SimpleOperation
           @result_class = Struct.new(*args)
         end
 
+        def self.success(*args)
+          @success_class = Success.generate(*args)
+        end
+
+        def self.failure(*args)
+          @failure_class = Failure.generate(*args)
+        end
+
         def result(*args)
           self.class.instance_variable_get(:@result_class).new(*args)
         end
+
+        def success(*args)
+          self.class.instance_variable_get(:@success_class).new(*args)
+        end
+
+        def failure(*args)
+          self.class.instance_variable_get(:@failure_class).new(*args)
+        end
+
+        alias_method :Result, :result
+        alias_method :Success, :success
+        alias_method :Failure, :failure
     end
   end
 

data/lib/simple_operation/failure.rb

@@ -0,0 +1,41 @@
+require_relative './wrapped_value'
+
+class SimpleOperation
+  module Failure
+
+    def self.generate(*args)
+      Struct.new(*args) do
+        include InstanceMethods
+      end
+    end
+
+    module InstanceMethods
+
+      def on_success
+        self
+      end
+
+      def on_failure(match_reason = nil)
+        if match_reason.nil? || (respond_to?(:reason) && reason == match_reason)
+          WrappedValue.new(yield self)
+        else
+          self
+        end
+      end
+
+      def success?
+        false
+      end
+
+      def failure?
+        true
+      end
+
+      def unwrap
+        self
+      end
+
+    end
+
+  end
+end

data/lib/simple_operation/success.rb

@@ -0,0 +1,37 @@
+require_relative './wrapped_value'
+
+class SimpleOperation
+  module Success
+
+    def self.generate(*args)
+      Struct.new(*args) do
+        include InstanceMethods
+      end
+    end
+
+    module InstanceMethods
+
+      def on_success
+        WrappedValue.new(yield self)
+      end
+
+      def on_failure(reason = nil)
+        self
+      end
+
+      def success?
+        true
+      end
+
+      def failure?
+        false
+      end
+
+      def unwrap
+        self
+      end
+
+    end
+
+  end
+end

data/lib/simple_operation/version.rb

@@ -1,3 +1,3 @@
 class SimpleOperation
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/simple_operation/wrapped_value.rb

@@ -0,0 +1,17 @@
+class SimpleOperation
+  class WrappedValue < SimpleDelegator
+
+    attr_reader :delegate_sd_obj
+
+    def on_success
+      self
+    end
+
+    def on_failure(reason = nil)
+      self
+    end
+
+    alias_method :unwrap, :delegate_sd_obj
+
+  end
+end

data/simple_operation.gemspec

@@ -20,4 +20,5 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.7"
   spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest"
 end

data/test/failure_test.rb

@@ -0,0 +1,63 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'simple_operation'
+require 'minitest/autorun'
+
+class FailureTest < Minitest::Test
+
+  FakeFailure = SimpleOperation::Failure.generate(:value)
+  FakeReasonFailure = SimpleOperation::Failure.generate(:reason)
+
+  def test_runs_correctly
+    assert SimpleOperation::Failure.generate(:value)
+  end
+
+  def test_has_correct_attributes
+    klass = SimpleOperation::Failure.generate(:name, :email)
+    instance = klass.new("Tom", "tom@tomtomtomtom.com")
+
+    assert_equal "Tom", instance.name
+    assert_equal "tom@tomtomtomtom.com", instance.email
+  end
+
+  def test_is_not_successful
+    refute FakeFailure.new("123").success?
+  end
+
+  def test_is_failure
+    assert FakeFailure.new("123").failure?
+  end
+
+  def test_returns_wrapped_value_on_failure
+    result = FakeFailure.new("123").on_failure { |s| s.value * 3 }
+
+    assert_equal SimpleOperation::WrappedValue.new("123123123"), result
+  end
+
+  def test_returns_wrapped_value_on_matching_reason
+    failure = FakeReasonFailure.new(:wrong_id)
+    result = failure.on_failure(:wrong_id) { |s| "this is #{s.reason}" }
+
+    assert_equal SimpleOperation::WrappedValue.new("this is wrong_id"), result
+  end
+
+  def test_returns_self_on_non_matching_reason
+    failure = FakeReasonFailure.new(:wrong_name)
+    result = failure.on_failure(:wrong_id) { |s| "this is #{s.reason}" }
+
+    assert_equal result, failure
+  end
+
+  def test_returns_self_on_success
+    failure = FakeFailure.new("123")
+    result = failure.on_success { |s| s.value * 4 }
+
+    assert_equal failure, result
+  end
+
+  def test_unwraps_self
+    failure = FakeFailure.new("123")
+
+    assert_equal failure, failure.unwrap
+  end
+end
+

data/test/simple_operation_test.rb

@@ -25,7 +25,7 @@ class SimpleOperationTest < Minitest::Test
   end
 
   def test_reader_is_assigned_default_value
-    assert_equal klass.new.send(:login), nil
+    assert_nil klass.new.send(:login)
   end
 
   def test_instance_has_call_method
@@ -58,6 +58,15 @@ class SimpleOperationTest < Minitest::Test
     refute result_klass.('Grzegorz').found
   end
 
+  def test_returns_success
+    assert success_failure_klass.('Arnvald').success?
+    assert success_failure_klass.('Arnvald').user == {name: 'Grzegorz'}
+  end
+
+  def test_returns_failure
+    refute success_failure_klass.('').success?
+    assert success_failure_klass.('').error = 'invalid login'
+  end
 
   def object
     klass.new('Arnvald')
@@ -71,6 +80,10 @@ class SimpleOperationTest < Minitest::Test
     FindUserResult
   end
 
+  def success_failure_klass
+    FindUserSuccessFailure
+  end
+
   FindUser = SimpleOperation.new(:login) do
     def call
       login == 'Arnvald'
@@ -85,4 +98,17 @@ class SimpleOperationTest < Minitest::Test
     end
   end
 
+  class FindUserSuccessFailure < SimpleOperation.new(:login)
+    success :user
+    failure :error
+
+    def call
+      if login == 'Arnvald'
+        Success({name: "Grzegorz"})
+      else
+        Failure("invalid login")
+      end
+    end
+  end
+
 end

data/test/success_test.rb

@@ -0,0 +1,47 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'simple_operation'
+require 'minitest/autorun'
+
+class SuccessTest < Minitest::Test
+
+  FakeSuccess = SimpleOperation::Success.generate(:value)
+
+  def test_runs_correctly
+    assert SimpleOperation::Success.generate(:value)
+  end
+
+  def test_has_correct_attributes
+    klass = SimpleOperation::Success.generate(:name, :email)
+    instance = klass.new("Tom", "tom@tomtomtomtom.com")
+
+    assert_equal "Tom", instance.name
+    assert_equal "tom@tomtomtomtom.com", instance.email
+  end
+
+  def test_is_successful
+    assert FakeSuccess.new("123").success?
+  end
+
+  def test_is_not_failure
+    refute FakeSuccess.new("123").failure?
+  end
+
+  def test_returns_wrapped_value_on_success
+    result = FakeSuccess.new("123").on_success { |s| s.value * 3 }
+
+    assert_equal SimpleOperation::WrappedValue.new("123123123"), result
+  end
+
+  def test_returns_self_on_failure
+    success = FakeSuccess.new("123")
+    result = success.on_failure { |s| s.value * 4 }
+
+    assert_equal success, result
+  end
+
+  def test_unwraps_self
+    success = FakeSuccess.new("123")
+
+    assert_equal success, success.unwrap
+  end
+end

data/test/wrapped_value_test.rb

@@ -0,0 +1,26 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'simple_operation'
+require 'minitest/autorun'
+
+class WrappedValueTest < Minitest::Test
+
+  def test_runs_correctly
+    assert SimpleOperation::WrappedValue.new("A")
+  end
+
+  def test_returns_self_on_success
+    value = SimpleOperation::WrappedValue.new("A")
+    assert_equal value, (value.on_success { |v| nil })
+  end
+
+  def test_returns_self_on_failure
+    value = SimpleOperation::WrappedValue.new("A")
+    assert_equal value, (value.on_failure { |v| nil })
+  end
+
+  def test_unwraps_value
+    value = SimpleOperation::WrappedValue.new("A")
+    assert_equal "A", value.unwrap
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_operation
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Grzegorz Witek
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-22 00:00:00.000000000 Z
+date: 2018-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: SimpleOperation is a very simple library that facilitates creating service
   objects
 email:
@@ -53,10 +67,16 @@ files:
 - Rakefile
 - lib/simple_operation.rb
 - lib/simple_operation/ext.rb
+- lib/simple_operation/failure.rb
+- lib/simple_operation/success.rb
 - lib/simple_operation/version.rb
+- lib/simple_operation/wrapped_value.rb
 - simple_operation.gemspec
+- test/failure_test.rb
 - test/simple_operation_ext_test.rb
 - test/simple_operation_test.rb
+- test/success_test.rb
+- test/wrapped_value_test.rb
 homepage: ''
 licenses:
 - MIT
@@ -77,10 +97,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
 summary: Create simple service object
 test_files:
+- test/failure_test.rb
 - test/simple_operation_ext_test.rb
 - test/simple_operation_test.rb
+- test/success_test.rb
+- test/wrapped_value_test.rb