dry-transaction 0.4.0

data/lib/dry/transaction/step.rb

@@ -0,0 +1,42 @@
+require "wisper"
+require "dry/transaction/step_failure"
+
+module Dry
+  module Transaction
+    # @api private
+    class Step
+      include Wisper::Publisher
+
+      attr_reader :step_name
+      attr_reader :operation
+      attr_reader :call_args
+
+      def initialize(step_name, operation, call_args = [])
+        @step_name = step_name
+        @operation = operation
+        @call_args = call_args
+      end
+
+      def with_call_args(*call_args)
+        self.class.new(step_name, operation, call_args)
+      end
+
+      def call(input)
+        args = call_args + [input]
+        result = operation.call(*args)
+
+        result.fmap { |value|
+          broadcast :"#{step_name}_success", value
+          value
+        }.or { |value|
+          broadcast :"#{step_name}_failure", *args, value
+          Left(StepFailure.new(step_name, value))
+        }
+      end
+
+      def arity
+        operation.arity
+      end
+    end
+  end
+end

data/lib/dry/transaction/step_adapters.rb

@@ -0,0 +1,27 @@
+require "forwardable"
+
+module Dry
+  module Transaction
+    module StepAdapters
+      @registry = {}
+
+      class << self
+        attr_reader :registry
+        private :registry
+
+        extend Forwardable
+        def_delegators :registry, :[], :each
+
+        # Register a step adapter.
+        #
+        # @param [Symbol] name the name to expose for adding steps to a transaction
+        # @param klass the step adapter class
+        #
+        # @api public
+        def register(name, klass)
+          registry[name.to_sym] = klass
+        end
+      end
+    end
+  end
+end

data/lib/dry/transaction/step_adapters/base.rb

@@ -0,0 +1,20 @@
+module Dry
+  module Transaction
+    module StepAdapters
+      # @api private
+      class Base
+        attr_reader :operation
+        attr_reader :options
+
+        def initialize(operation, options)
+          @operation = operation
+          @options = options
+        end
+
+        def arity
+          operation.is_a?(Proc) ? operation.arity : operation.method(:call).arity
+        end
+      end
+    end
+  end
+end

data/lib/dry/transaction/step_adapters/map.rb

@@ -0,0 +1,14 @@
+module Dry
+  module Transaction
+    module StepAdapters
+      # @api private
+      class Map < Base
+        def call(*args, input)
+          Right(operation.call(*args, input))
+        end
+      end
+
+      register :map, Map
+    end
+  end
+end

data/lib/dry/transaction/step_adapters/raw.rb

@@ -0,0 +1,14 @@
+module Dry
+  module Transaction
+    module StepAdapters
+      # @api private
+      class Raw < Base
+        def call(*args, input)
+          operation.call(*args, input)
+        end
+      end
+
+      register :step, Raw
+    end
+  end
+end

data/lib/dry/transaction/step_adapters/tee.rb

@@ -0,0 +1,15 @@
+module Dry
+  module Transaction
+    module StepAdapters
+      # @api private
+      class Tee < Base
+        def call(*args, input)
+          operation.call(*args, input)
+          Right(input)
+        end
+      end
+
+      register :tee, Tee
+    end
+  end
+end

data/lib/dry/transaction/step_adapters/try.rb

@@ -0,0 +1,21 @@
+module Dry
+  module Transaction
+    module StepAdapters
+      # @api private
+      class Try < Base
+        def initialize(*)
+          super
+          raise ArgumentError, "+try+ steps require one or more exception classes provided via +catch:+" unless options[:catch]
+        end
+
+        def call(*args, input)
+          Right(operation.call(*args, input))
+        rescue *Array(options[:catch]) => e
+          Left(e)
+        end
+      end
+
+      register :try, Try
+    end
+  end
+end

data/lib/dry/transaction/step_failure.rb

@@ -0,0 +1,20 @@
+module Dry
+  module Transaction
+    class StepFailure < BasicObject
+      attr_reader :__step_name
+
+      def initialize(step_name, object)
+        @__step_name = step_name
+        @__object = object
+      end
+
+      def method_missing(name, *args, &block)
+        @__object.send(name, *args, &block)
+      end
+
+      def ==(other)
+        @__object == other
+      end
+    end
+  end
+end

data/lib/dry/transaction/version.rb

@@ -0,0 +1,6 @@
+module Dry
+  # Business transaction DSL.
+  module Transaction
+    VERSION = "0.4.0".freeze
+  end
+end

data/spec/examples.txt

@@ -0,0 +1,41 @@
+example_id                                               | status | run_time        |
+-------------------------------------------------------- | ------ | --------------- |
+./spec/integration/passing_step_arguments_spec.rb[1:1:1] | passed | 0.00101 seconds |
+./spec/integration/passing_step_arguments_spec.rb[1:2:1] | passed | 0.00284 seconds |
+./spec/integration/passing_step_arguments_spec.rb[1:3:1] | passed | 0.00047 seconds |
+./spec/integration/publishing_step_events_spec.rb[1:1:1] | passed | 0.00063 seconds |
+./spec/integration/publishing_step_events_spec.rb[1:1:2] | passed | 0.00518 seconds |
+./spec/integration/publishing_step_events_spec.rb[1:2:1] | passed | 0.00041 seconds |
+./spec/integration/publishing_step_events_spec.rb[1:2:2] | passed | 0.00036 seconds |
+./spec/integration/transaction_spec.rb[1:1:1]            | passed | 0.00166 seconds |
+./spec/integration/transaction_spec.rb[1:1:2]            | passed | 0.00049 seconds |
+./spec/integration/transaction_spec.rb[1:1:3]            | passed | 0.00045 seconds |
+./spec/integration/transaction_spec.rb[1:1:4]            | passed | 0.00101 seconds |
+./spec/integration/transaction_spec.rb[1:1:5]            | passed | 0.00028 seconds |
+./spec/integration/transaction_spec.rb[1:2:1]            | passed | 0.00024 seconds |
+./spec/integration/transaction_spec.rb[1:2:2]            | passed | 0.00022 seconds |
+./spec/integration/transaction_spec.rb[1:2:3]            | passed | 0.00033 seconds |
+./spec/integration/transaction_spec.rb[1:2:4]            | passed | 0.00038 seconds |
+./spec/integration/transaction_spec.rb[1:2:5]            | passed | 0.00021 seconds |
+./spec/integration/transaction_spec.rb[1:2:6]            | passed | 0.00022 seconds |
+./spec/integration/transaction_spec.rb[1:3:1]            | passed | 0.00214 seconds |
+./spec/integration/transaction_spec.rb[1:3:2]            | passed | 0.00037 seconds |
+./spec/integration/transaction_spec.rb[1:3:3]            | passed | 0.00022 seconds |
+./spec/unit/sequence_spec.rb[1:1:1]                      | passed | 0.00014 seconds |
+./spec/unit/sequence_spec.rb[1:1:2]                      | passed | 0.00032 seconds |
+./spec/unit/sequence_spec.rb[1:1:3]                      | passed | 0.00032 seconds |
+./spec/unit/sequence_spec.rb[1:1:4]                      | passed | 0.00013 seconds |
+./spec/unit/sequence_spec.rb[1:2:1]                      | passed | 0.00031 seconds |
+./spec/unit/sequence_spec.rb[1:2:2]                      | passed | 0.00017 seconds |
+./spec/unit/sequence_spec.rb[1:2:3]                      | passed | 0.00012 seconds |
+./spec/unit/sequence_spec.rb[1:2:4]                      | passed | 0.00013 seconds |
+./spec/unit/sequence_spec.rb[1:3:1]                      | passed | 0.00013 seconds |
+./spec/unit/sequence_spec.rb[1:3:2]                      | passed | 0.00014 seconds |
+./spec/unit/sequence_spec.rb[1:4:1]                      | passed | 0.00034 seconds |
+./spec/unit/sequence_spec.rb[1:4:2]                      | passed | 0.00031 seconds |
+./spec/unit/sequence_spec.rb[1:4:3]                      | passed | 0.00016 seconds |
+./spec/unit/sequence_spec.rb[1:4:4]                      | passed | 0.00011 seconds |
+./spec/unit/sequence_spec.rb[1:4:5:1]                    | passed | 0.00017 seconds |
+./spec/unit/sequence_spec.rb[1:4:5:2]                    | passed | 0.00033 seconds |
+./spec/unit/sequence_spec.rb[1:4:6:1]                    | passed | 0.00033 seconds |
+./spec/unit/sequence_spec.rb[1:4:6:2]                    | passed | 0.00015 seconds |

data/spec/integration/passing_step_arguments_spec.rb

@@ -0,0 +1,50 @@
+RSpec.describe "Passing additional arguments to step operations" do
+  let(:call_transaction) { transaction.call(input, step_options) }
+
+  let(:transaction) {
+    Dry.Transaction(container: container) do
+      map :process
+      try :validate, catch: Test::NotValidError
+      tee :persist
+    end
+  }
+
+  let(:container) {
+    {
+      process:  -> input { {name: input["name"], email: input["email"]} },
+      validate: -> allowed, input { !input[:email].include?(allowed) ? raise(Test::NotValidError, "email not allowed") : input },
+      persist:  -> input { Test::DB << input and true }
+    }
+  }
+
+  let(:input) { {"name" => "Jane", "email" => "jane@doe.com"} }
+
+  before do
+    Test::NotValidError = Class.new(StandardError)
+    Test::DB = []
+  end
+
+  context "required arguments provided" do
+    let(:step_options) { {validate: ["doe.com"]} }
+
+    it "passes the arguments and calls the operations successfully" do
+      expect(call_transaction).to be_a Kleisli::Either::Right
+    end
+  end
+
+  context "required arguments not provided" do
+    let(:step_options) { {} }
+
+    it "raises an ArgumentError" do
+      expect { call_transaction }.to raise_error(ArgumentError)
+    end
+  end
+
+  context "spurious arguments provided" do
+    let(:step_options) { {validate: ["doe.com"], bogus: ["not matching any step"]} }
+
+    it "raises an ArgumentError" do
+      expect { call_transaction }.to raise_error(ArgumentError)
+    end
+  end
+end

data/spec/integration/publishing_step_events_spec.rb

@@ -0,0 +1,65 @@
+RSpec.describe "publishing step events" do
+  let(:transaction) {
+    Dry.Transaction(container: container) do
+      map :process
+      step :verify
+      tee :persist
+    end
+  }
+
+  let(:container) {
+    {
+      process:  -> input { {name: input["name"]} },
+      verify:   -> input { input[:name].to_s != "" ? Right(input) : Left("no name") },
+      persist:  -> input { Test::DB << input and true }
+    }
+  }
+
+  let(:subscriber) { spy(:subscriber) }
+
+  before do
+    Test::DB = []
+  end
+
+  context "subscribing to all step events" do
+    before do
+      transaction.subscribe(subscriber)
+    end
+
+    specify "subscriber receives success events" do
+      transaction.call("name" => "Jane")
+
+      expect(subscriber).to have_received(:process_success).with(name: "Jane")
+      expect(subscriber).to have_received(:verify_success).with(name: "Jane")
+      expect(subscriber).to have_received(:persist_success).with(name: "Jane")
+    end
+
+    specify "subsriber receives success events for passing steps, a failure event for the failing step, and no subsequent events" do
+      transaction.call("name" => "")
+
+      expect(subscriber).to have_received(:process_success).with(name: "")
+      expect(subscriber).to have_received(:verify_failure).with({name: ""}, "no name")
+      expect(subscriber).not_to have_received(:persist_success)
+    end
+  end
+
+  context "subscribing to particular step events" do
+    before do
+      transaction.subscribe(verify: subscriber)
+    end
+
+    specify "subscriber receives success event for the specified step" do
+      transaction.call("name" => "Jane")
+
+      expect(subscriber).to have_received(:verify_success).with(name: "Jane")
+      expect(subscriber).not_to have_received(:process_success)
+      expect(subscriber).not_to have_received(:persist_success)
+    end
+
+    specify "subscriber receives failure event for the specified step" do
+      transaction.call("name" => "")
+
+      expect(subscriber).to have_received(:verify_failure).with({name: ""}, "no name")
+    end
+  end
+end

data/spec/integration/transaction_spec.rb

@@ -0,0 +1,139 @@
+RSpec.describe "Transactions" do
+  let(:transaction) {
+    Dry.Transaction(container: container) do
+      map :process
+      step :verify
+      try :validate, catch: Test::NotValidError
+      tee :persist
+    end
+  }
+
+  let(:container) {
+    {
+      process:  -> input { {name: input["name"], email: input["email"]} },
+      verify:   -> input { Right(input) },
+      validate: -> input { input[:email].nil? ? raise(Test::NotValidError, "email required") : input },
+      persist:  -> input { Test::DB << input and true }
+    }
+  }
+
+  before do
+    Test::NotValidError = Class.new(StandardError)
+    Test::DB = []
+  end
+
+  context "successful" do
+    let(:input) { {"name" => "Jane", "email" => "jane@doe.com"} }
+
+    it "calls the operations" do
+      transaction.call(input)
+      expect(Test::DB).to include(name: "Jane", email: "jane@doe.com")
+    end
+
+    it "returns a success" do
+      expect(transaction.call(input)).to be_a Kleisli::Either::Right
+    end
+
+    it "wraps the result of the final operation" do
+      expect(transaction.call(input).value).to eq(name: "Jane", email: "jane@doe.com")
+    end
+
+    it "can be called multiple times to the same effect" do
+      transaction.call(input)
+      transaction.call(input)
+
+      expect(Test::DB[0]).to eq(name: "Jane", email: "jane@doe.com")
+      expect(Test::DB[1]).to eq(name: "Jane", email: "jane@doe.com")
+    end
+
+    it "supports matching on success" do
+      results = []
+
+      transaction.call(input) do |m|
+        m.success do |value|
+          results << "success for #{value[:email]}"
+        end
+      end
+
+      expect(results.first).to eq "success for jane@doe.com"
+    end
+  end
+
+  context "failed in a try step" do
+    let(:input) { {"name" => "Jane"} }
+
+    it "does not run subsequent operations" do
+      transaction.call(input)
+      expect(Test::DB).to be_empty
+    end
+
+    it "returns a failure" do
+      expect(transaction.call(input)).to be_a Kleisli::Either::Left
+    end
+
+    it "wraps the result of the failing operation" do
+      expect(transaction.call(input).value).to be_a Test::NotValidError
+    end
+
+    it "supports matching on failure" do
+      results = []
+
+      transaction.call(input) do |m|
+        m.failure do |value|
+          results << "Failed: #{value}"
+        end
+      end
+
+      expect(results.first).to eq "Failed: email required"
+    end
+
+    it "supports matching on specific step failures" do
+      results = []
+
+      transaction.call(input) do |m|
+        m.failure :validate do |value|
+          results << "Validation failure: #{value}"
+        end
+      end
+
+      expect(results.first).to eq "Validation failure: email required"
+    end
+
+    it "supports matching on un-named step failures" do
+      results = []
+
+      transaction.call(input) do |m|
+        m.failure :some_other_step do |value|
+          results << "Some other step failure"
+        end
+
+        m.failure do |value|
+          results << "Catch-all failure: #{value}"
+        end
+      end
+
+      expect(results.first).to eq "Catch-all failure: email required"
+    end
+  end
+
+  context "failed in a raw step" do
+    let(:input) { {"name" => "Jane", "email" => "jane@doe.com"} }
+
+    before do
+      container[:verify] = -> input { Left("raw failure") }
+    end
+
+    it "does not run subsequent operations" do
+      transaction.call(input)
+      expect(Test::DB).to be_empty
+    end
+
+    it "returns a failure" do
+      expect(transaction.call(input)).to be_a Kleisli::Either::Left
+    end
+
+    it "returns the failing value from the operation" do
+      expect(transaction.call(input).value).to eq "raw failure"
+    end
+  end
+end