dry-transaction 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dd63f3d5d018054cf586e579ccef6a9850ecce0a
+  data.tar.gz: 1c0028e352968ef521ff95b14d94e91adbbd4c6f
+SHA512:
+  metadata.gz: 1e6c390997dc3f2273d2c2cbb55dc395a7f29011319f6f636a0ff3235f4f2110843ddb4dd2a200dda19a474cebf7228b0a55d85839fe0f243eef9b9d8e159bba
+  data.tar.gz: 50b11cf0a69818f259881bfbc6b7fb50d048d932457dfdb3fd87e6d38f188772534d5810b1d59a428f76697e4838fa0760897f38c6aafee35b5ca89c287c658c

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,49 @@
+PATH
+  remote: .
+  specs:
+    dry-transaction (0.4.0)
+      kleisli
+      wisper (>= 1.6.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    json (1.8.3)
+    kleisli (0.2.7)
+    rake (10.4.2)
+    rspec (3.3.0)
+      rspec-core (~> 3.3.0)
+      rspec-expectations (~> 3.3.0)
+      rspec-mocks (~> 3.3.0)
+    rspec-core (3.3.2)
+      rspec-support (~> 3.3.0)
+    rspec-expectations (3.3.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-mocks (3.3.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-support (3.3.0)
+    simplecov (0.10.0)
+      docile (~> 1.1.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    wisper (1.6.1)
+    yard (0.8.7.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.10)
+  dry-transaction!
+  rake (~> 10.4.2)
+  rspec (~> 3.3.0)
+  simplecov (~> 0.10.0)
+  yard
+
+BUNDLED WITH
+   1.11.2

data/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2015-2016 [Icelab](http://icelab.com.au/).
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,201 @@
+[gitter]: https://gitter.im/dry-rb/chat
+[gem]: https://rubygems.org/gems/dry-transaction
+[code_climate]: https://codeclimate.com/github/dry-rb/dry-transaction
+[inch]: http://inch-ci.org/github/dry-rb/dry-transaction
+
+# dry-transaction [![Join the Gitter chat](https://badges.gitter.im/Join%20Chat.svg)][gitter]
+
+[![Gem Version](https://img.shields.io/gem/v/dry-transaction.svg)][gem]
+[![Code Climate](https://img.shields.io/codeclimate/github/dry-rb/dry-transaction.svg)][code_climate]
+[![API Documentation Coverage](http://inch-ci.org/github/dry-rb/dry-transaction.svg)][inch]
+
+dry-transaction is a business transaction DSL. It provides a simple way to define a complex business transaction that includes processing by many different objects. It makes error handling a primary concern by using a “[Railway Oriented Programming](http://fsharpforfunandprofit.com/rop/)” approach for capturing and returning errors from any step in the transaction.
+
+dry-transaction is based on the following ideas:
+
+* A business transaction is a series of operations where each can fail and stop processing.
+* A business transaction resolves its dependencies using an external container object and it doesn’t know any details about the individual operation objects except their identifiers.
+* A business transaction can describe its steps on an abstract level without being coupled to any details about how individual operations work.
+* A business transaction doesn’t have any state.
+* Each operation shouldn’t accumulate state, instead it should receive an input and return an output without causing any side-effects.
+* The only interface of a an operation is `#call(input)`.
+* Each operation provides a meaningful functionality and can be reused.
+* Errors in any operation can be easily caught and handled as part of the normal application flow.
+
+## Why?
+
+Requiring a business transaction’s steps to exist as independent operations directly addressable via a container means that they can be tested in isolation and easily reused throughout your application. Following from this, keeping the business transaction to a series of high-level, declarative steps ensures that it’s easy to understand at a glance.
+
+The output of each step is wrapped in a [Kleisli](https://github.com/txus/kleisli) `Either` object (`Right` for success or `Left` for failure). This allows the steps to be chained together and ensures that processing stops in the case of a failure. Returning an `Either` from the overall transaction also allows for error handling to remain a primary concern without it getting in the way of tidy, straightforward operation logic. Wrapping the step output also means that you can work with a wide variety of operations within your application – they don’t need to return an `Either` already.
+
+## Usage
+
+### Container
+
+All you need to use dry-transaction is a container to hold your application’s operations. Each operation must respond to `#call(input)`.
+
+The operations will be resolved from the container via `#[]`. For our examples, we’ll use a plain hash:
+
+```ruby
+container = {
+  process:  -> input { {name: input["name"], email: input["email"]} },
+  validate: -> input { input[:email].nil? ? raise(ValidationFailure, "not valid") : input },
+  persist:  -> input { DB << input and true }
+}
+```
+
+For larger apps, you may like to consider something like [dry-container](https://github.com/dryrb/dry-container).
+
+### Defining a transaction
+
+Define a transaction to bring your opererations together:
+
+```ruby
+save_user = Dry.Transaction(container: container) do
+  map :process
+  try :validate, catch: ValidationFailure
+  tee :persist
+end
+```
+
+Operations are formed into steps using _step adapters._ Step adapters wrap the output of your operations to make them easy to integrate into a transaction. The following adapters are available:
+
+* `step` – the operation already returns an `Either` object (`Right(output)` for success and `Left(output)` for failure), and needs no special handling.
+* `map` – any output is considered successful and returned as `Right(output)`
+* `try` – the operation may raise an exception in an error case. This is caught and returned as `Left(exception)`. The output is otherwise returned as `Right(output)`.
+* `tee` – the operation interacts with some external system and has no meaningful output. The original input is passed through and returned as `Right(input)`.
+
+### Calling a transaction
+
+Calling a transaction will run its operations in their specified order, with the output of each operation becoming the input for the next.
+
+```ruby
+DB = []
+
+save_user.call("name" => "Jane", "email" => "jane@doe.com")
+# => Right({:name=>"Jane", :email=>"jane@doe.com"})
+
+DB
+# => [{:name=>"Jane", :email=>"jane@doe.com"}]
+```
+
+Each transaction returns a result value wrapped in a `Left` or `Right` object (based on the output of its final step). You can handle these results (including errors arising from particular steps) with a match block:
+
+```ruby
+save_user.call(name: "Jane", email: "jane@doe.com") do |m|
+  m.success do |value|
+    puts "Succeeded!"
+  end
+
+  m.failure :validate do |error|
+    # In a more realistic example, you’d loop through a list of messages in `errors`.
+    puts "Please provide an email address."
+  end
+
+  m.failure do |error|
+    puts "Couldn’t save this user."
+  end
+end
+```
+
+### Passing additional step arguments
+
+Additional arguments for step operations can be passed at the time of calling your transaction. Provide these arguments as an array, and they’ll be [splatted](https://endofline.wordpress.com/2011/01/21/the-strange-ruby-splat/) into the front of the operation’s arguments. This means that transactions can effectively support operations with any sort of `#call(*args, input)` interface.
+
+```ruby
+DB = []
+
+container = {
+  process:  -> input { {name: input["name"], email: input["email"]} },
+  validate: -> allowed, input { input[:email].include?(allowed) ? raise(ValidationFailure, "not allowed") : input },
+  persist:  -> input { DB << input and true }
+}
+
+save_user = Dry.Transaction(container: container) do
+  map :process
+  try :validate, catch: ValidationFailure
+  tee :persist
+end
+
+input = {"name" => "Jane", "email" => "jane@doe.com"}
+save_user.call(input, validate: ["doe.com"])
+# => Right({:name=>"Jane", :email=>"jane@doe.com"})
+
+save_user.call(input, validate: ["smith.com"])
+# => Left("not allowed")
+```
+
+### Subscribing to step notifications
+
+As well as pattern matching on the final transaction result, you can subscribe to individual steps and trigger specific behaviour based on their success or failure:
+
+```ruby
+NOTIFICATIONS = []
+
+module UserPersistListener
+  extend self
+
+  def persist_success(user)
+    NOTIFICATIONS << "#{user[:email]} persisted"
+  end
+
+  def persist_failure(user)
+    NOTIFICATIONS << "#{user[:email]} failed to persist"
+  end
+end
+
+
+input = {"name" => "Jane", "email" => "jane@doe.com"}
+
+save_user.subscribe(persist: UserPersistListener)
+save_user.call(input, validate: ["doe.com"])
+
+NOTIFICATIONS
+# => ["jane@doe.com persisted"]
+```
+
+This pub/sub mechanism is provided by the [Wisper](https://github.com/krisleech/wisper) gem. You can subscribe to specific steps using the `#subscribe(step_name: listener)` API, or subscribe to all steps via `#subscribe(listener)`.
+
+### Extending transactions
+
+You can extend existing transactions by inserting or removing steps. See the [API docs](http://www.rubydoc.info/github/dry-rb/dry-transaction/Dry/Transaction/Sequence) for more information.
+
+### Working with a larger container
+
+In practice, your container won’t be a trivial collection of generically named operations. You can keep your transaction step names simple by using the `with:` option to provide the identifiers for the operations within your container:
+
+```ruby
+save_user = Dry.Transaction(container: large_whole_app_container) do
+  map :process, with: "attributes.user"
+  try :validate, with: "validations.user", catch: ValidationFailure
+  tee :persist, with: "persistance.commands.update_user"
+end
+```
+
+## Installation
+
+Add this line to your application’s `Gemfile`:
+
+```ruby
+gem "dry-transaction"
+```
+
+Run `bundle` to install the gem.
+
+## Documentation
+
+View the [full API documentation](http://www.rubydoc.info/github/dry-rb/dry-transaction) on RubyDoc.info.
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](http://github.com/dry-rb/dry-transaction).
+
+## Credits
+
+dry-transaction is developed and maintained by [Icelab](http://icelab.com.au/).
+
+dry-transaction’s error handling is based on Scott Wlaschin’s [Railway Oriented Programming](http://fsharpforfunandprofit.com/rop/), found via Zohaib Rauf’s [Railway Oriented Programming in Elixir](http://zohaib.me/railway-programming-pattern-in-elixir/) blog post. dry-transaction’s behavior as a business transaction library draws heavy inspiration from Piotr Solnica’s [Transflow](http://github.com/solnic/transflow) and Gilbert B Garza’s [Solid Use Case](https://github.com/mindeavor/solid_use_case). Josep M. Bach’s [Kleisli](https://github.com/txus/kleisli) gem makes functional programming patterns in Ruby accessible and fun. Thank you all!
+
+## License
+
+Copyright © 2015-2016 [Icelab](http://icelab.com.au/). dry-transaction is free software, and may be redistributed under the terms specified in the [license](LICENSE.md).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new
+
+task default: :spec

data/lib/dry-transaction.rb

@@ -0,0 +1 @@
+require "dry/transaction"

data/lib/dry/transaction.rb

@@ -0,0 +1,54 @@
+require "kleisli"
+require "dry/transaction/version"
+require "dry/transaction/dsl"
+
+module Dry
+  # Define a business transaction.
+  #
+  # A business transaction is a series of callable operation objects that
+  # receive input and produce an output.
+  #
+  # The operations should be addressable via `#[]` in a container object that
+  # you pass when creating the transaction. The operations must respond to
+  # `#call(*args, input)`.
+  #
+  # Each operation will be called in the order it was specified in your
+  # transaction, with its output is passed as the input to the next operation.
+  # Operations will only be called if the previous step was a success.
+  #
+  # A step is successful when it returns a [Kleisli](kleisli) `Right` object
+  # wrapping its output value. A step is a failure when it returns a `Left`
+  # object.  If your operations already return a `Right` or `Left`, they can be
+  # added to your operation as plain `step` steps.
+  #
+  # If your operations don't already return `Right` or `Left`, then they can be
+  # added to the transaction with the following steps:
+  #
+  # * `map` --- wrap the output of the operation in a `Right`
+  # * `try` --- wrap the output of the operation in a `Right`, unless a certain
+  #   exception is raised, which will be caught and returned as a `Left`.
+  # * `tee` --- ignore the output of the operation and pass through its original
+  #   input as a `Right`.
+  #
+  # [kleisli]: https://rubygems.org/gems/kleisli
+  #
+  # @example
+  #   container = {do_first: some_obj, do_second: some_obj}
+  #
+  #   my_transaction = Dry.Transaction(container: container) do
+  #     step :do_first
+  #     step :do_second
+  #   end
+  #
+  #   my_transaction.call(some_input)
+  #
+  # @param options [Hash] the options hash
+  # @option options [#[]] :container the operations container
+  #
+  # @return [Dry::Transaction::Steps] the transaction object
+  #
+  # @api public
+  def self.Transaction(options = {}, &block)
+    Transaction::DSL.new(options, &block).call
+  end
+end

data/lib/dry/transaction/dsl.rb

@@ -0,0 +1,44 @@
+require "dry/transaction/step"
+require "dry/transaction/step_adapters"
+require "dry/transaction/step_adapters/base"
+require "dry/transaction/step_adapters/map"
+require "dry/transaction/step_adapters/raw"
+require "dry/transaction/step_adapters/tee"
+require "dry/transaction/step_adapters/try"
+require "dry/transaction/sequence"
+
+module Dry
+  module Transaction
+    class DSL
+      # @api private
+      attr_reader :options
+
+      # @api private
+      attr_reader :container
+
+      # @api private
+      attr_reader :steps
+
+      # @api private
+      def initialize(options, &block)
+        @options = options
+        @container = options.fetch(:container)
+        @steps = []
+
+        instance_exec(&block)
+      end
+
+      StepAdapters.each do |adapter_name, adapter_class|
+        define_method adapter_name do |step_name, options = {}|
+          operation = container[options.fetch(:with, step_name)]
+          steps << Step.new(step_name, adapter_class.new(operation, options))
+        end
+      end
+
+      # @api private
+      def call
+        Sequence.new(steps)
+      end
+    end
+  end
+end

data/lib/dry/transaction/result_matcher.rb

@@ -0,0 +1,26 @@
+module Dry
+  module Transaction
+    class ResultMatcher
+      attr_reader :result
+      attr_reader :output
+
+      def initialize(result)
+        @result = result
+      end
+
+      def success(&block)
+        return output unless result.is_a?(Kleisli::Either::Right)
+
+        @output = block.call(result.value)
+      end
+
+      def failure(step_name = nil, &block)
+        return output unless result.is_a?(Kleisli::Either::Left)
+
+        if step_name.nil? || step_name == result.value.__step_name
+          @output = block.call(result.value)
+        end
+      end
+    end
+  end
+end

data/lib/dry/transaction/sequence.rb

@@ -0,0 +1,296 @@
+require "dry/transaction/result_matcher"
+
+module Dry
+  module Transaction
+    class Sequence
+      # @api private
+      attr_reader :steps
+
+      # @api private
+      def initialize(steps)
+        @steps = steps
+      end
+
+      # Run the transaction.
+      #
+      # Each operation will be called in the order it was specified, with its
+      # output passed as input to the next operation. Operations will only be
+      # called if the previous step was a success.
+      #
+      # If any of the operations require extra arguments beyond the main input
+      # e.g. with a signature like `#call(something_else, input)`, then you
+      # must pass the extra arguments as arrays for each step in the options
+      # hash.
+      #
+      # @example Running a transaction
+      #   my_transaction.call(some_input)
+      #
+      # @example Running a transaction with extra step arguments
+      #   my_transaction.call(some_input, step_name: [extra_argument])
+      #
+      # The return value will be the output from the last operation, wrapped
+      # in a [Kleisli](kleisli) `Either` object, a `Right` for a successful
+      # transaction or a `Left` for a failed transaction.
+      #
+      # [kleisli]: https://rubygems.org/gems/kleisli
+      #
+      # @param input
+      # @param options [Hash] extra step arguments
+      #
+      # @return [Right, Left] output from the final step
+      #
+      # @api public
+      def call(input, options = {}, &block)
+        assert_valid_options(options)
+        assert_options_satisfy_step_arity(options)
+
+        steps = steps_with_options_applied(options)
+        result = steps.inject(Right(input), :>>)
+
+        if block
+          block.call(ResultMatcher.new(result))
+        else
+          result
+        end
+      end
+      alias_method :[], :call
+
+      # Subscribe to notifications from steps.
+      #
+      # When each step completes, it will send a `[step_name]_success` or
+      # `[step_name]_failure` message to any subscribers.
+      #
+      # For example, if you had a step called `persist`, then it would send
+      # either `persist_success` or `persist_failure` messages to subscribers
+      # after the operation completes.
+      #
+      # Pass a single object to subscribe to notifications from all steps, or
+      # pass a hash with step names as keys to subscribe to notifications from
+      # specific steps.
+      #
+      # @example Subscribing to notifications from all steps
+      #   my_transaction.subscribe(my_listener)
+      #
+      # @example Subscribing to notifications from specific steps
+      #   my_transaction.subscirbe(some_step: my_listener, another_step: another_listener)
+      #
+      # Notifications are implemented using the [Wisper](wisper) gem.
+      #
+      # [wisper]: https://rubygems.org/gems/wisper
+      #
+      # @param listeners [Object, Hash{Symbol => Object}] the listener object or
+      #     hash of steps and listeners
+      #
+      # @api public
+      def subscribe(listeners)
+        if listeners.is_a?(Hash)
+          listeners.each do |step_name, listener|
+            steps.detect { |step| step.step_name == step_name }.subscribe(listener)
+          end
+        else
+          steps.each do |step|
+            step.subscribe(listeners)
+          end
+        end
+
+        self
+      end
+
+      # Return a transaction with the steps from the provided transaction
+      # prepended onto the beginning of the steps in `self`.
+      #
+      # @example Prepend an existing transaction
+      #   my_transaction = Dry.Transaction(container: container) do
+      #     step :first
+      #     step :second
+      #   end
+      #
+      #   other_transaction = Dry.Transaction(container: container) do
+      #     step :another
+      #   end
+      #
+      #   my_transaction.prepend(other_transaction)
+      #
+      # @example Prepend a transaction defined inline
+      #   my_transaction = Dry.Transaction(container: container) do
+      #     step :first
+      #     step :second
+      #   end
+      #
+      #   my_transaction.prepend(container: container) do
+      #     step :another
+      #   end
+      #
+      # @param other [Dry::Transaction::Sequence] the transaction to prepend.
+      #     Optional if you will define a transaction inline via a block.
+      # @param options [Hash] the options hash for defining a transaction inline
+      #     via a block. Optional if the transaction is passed directly as
+      #     `other`.
+      # @option options [#[]] :container the operations container
+      #
+      # @return [Dry::Transaction::Sequence] the modified transaction object
+      #
+      # @api public
+      def prepend(other = nil, **options, &block)
+        other = accept_or_build_transaction(other, **options, &block)
+
+        self.class.new(other.steps + steps)
+      end
+
+      # Return a transaction with the steps from the provided transaction
+      # appended onto the end of the steps in `self`.
+      #
+      # @example Append an existing transaction
+      #   my_transaction = Dry.Transaction(container: container) do
+      #     step :first
+      #     step :second
+      #   end
+      #
+      #   other_transaction = Dry.Transaction(container: container) do
+      #     step :another
+      #   end
+      #
+      #   my_transaction.append(other_transaction)
+      #
+      # @example Append a transaction defined inline
+      #   my_transaction = Dry.Transaction(container: container) do
+      #     step :first
+      #     step :second
+      #   end
+      #
+      #   my_transaction.append(container: container) do
+      #     step :another
+      #   end
+      #
+      # @param other [Dry::Transaction::Sequence] the transaction to append.
+      #     Optional if you will define a transaction inline via a block.
+      # @param options [Hash] the options hash for defining a transaction inline
+      #     via a block. Optional if the transaction is passed directly as
+      #     `other`.
+      # @option options [#[]] :container the operations container
+      #
+      # @return [Dry::Transaction::Sequence] the modified transaction object
+      #
+      # @api public
+      def append(other = nil, **options, &block)
+        other = accept_or_build_transaction(other, **options, &block)
+
+        self.class.new(steps + other.steps)
+      end
+
+      # Return a transaction with the steps from the provided transaction
+      # inserted into a specific place among the steps in `self`.
+      #
+      # Transactions can be inserted either before or after a named step.
+      #
+      # @example Insert an existing transaction (before a step)
+      #   my_transaction = Dry.Transaction(container: container) do
+      #     step :first
+      #     step :second
+      #   end
+      #
+      #   other_transaction = Dry.Transaction(container: container) do
+      #     step :another
+      #   end
+      #
+      #   my_transaction.insert(other_transaction, before: :second)
+      #
+      # @example Append a transaction defined inline (after a step)
+      #   my_transaction = Dry.Transaction(container: container) do
+      #     step :first
+      #     step :second
+      #   end
+      #
+      #   my_transaction.insert(after: :first, container: container) do
+      #     step :another
+      #   end
+      #
+      # @param other [Dry::Transaction::Sequence] the transaction to append.
+      #     Optional if you will define a transaction inline via a block.
+      # @param before [Symbol] the name of the step before which the
+      #     transaction should be inserted (provide either this or `after`)
+      # @param after [Symbol] the name of the step after which the transaction
+      #     should be inserted (provide either this or `before`)
+      # @param options [Hash] the options hash for defining a transaction
+      #     inline via a block. Optional if the transaction is passed directly
+      #     as `other`.
+      # @option options [#[]] :container the operations container
+      #
+      # @return [Dry::Transaction::Sequence] the modified transaction object
+      #
+      # @api public
+      def insert(other = nil, before: nil, after: nil, **options, &block)
+        insertion_step = before || after
+        unless steps.map(&:step_name).include?(insertion_step)
+          raise ArgumentError, "+#{insertion_step}+ is not a valid step name"
+        end
+
+        other = accept_or_build_transaction(other, **options, &block)
+        index = steps.index { |step| step.step_name == insertion_step } + (!!after ? 1 : 0)
+
+        self.class.new(steps.dup.insert(index, *other.steps))
+      end
+
+      # @overload remove(step, ...)
+      #   Return a transaction with steps removed.
+      #
+      #   @example
+      #     my_transaction = Dry.Transaction(container: container) do
+      #       step :first
+      #       step :second
+      #       step :third
+      #     end
+      #
+      #     my_transaction.remove(:first, :third)
+      #
+      #   @param step [Symbol] the names of a step to remove
+      #   @param ... [Symbol] more names of steps to remove
+      #
+      #   @return [Dry::Transaction::Sequence] the modified transaction object
+      #
+      #   @api public
+      def remove(*steps_to_remove)
+        self.class.new(steps.reject { |step| steps_to_remove.include?(step.step_name) })
+      end
+
+      private
+
+      def assert_valid_options(options)
+        options.each_key do |step_name|
+          unless steps.map(&:step_name).include?(step_name)
+            raise ArgumentError, "+#{step_name}+ is not a valid step name"
+          end
+        end
+      end
+
+      def assert_options_satisfy_step_arity(options)
+        steps.each do |step|
+          args_required = step.arity >= 0 ? step.arity : ~step.arity
+          args_supplied = options.fetch(step.step_name, []).length + 1 # add 1 for main `input`
+
+          if args_required > args_supplied
+            raise ArgumentError, "not enough options for step +#{step.step_name}+"
+          end
+        end
+      end
+
+      def steps_with_options_applied(options)
+        steps.map { |step|
+          if (args = options[step.step_name])
+            step.with_call_args(*args)
+          else
+            step
+          end
+        }
+      end
+
+      def accept_or_build_transaction(other_transaction = nil, **options, &block)
+        unless other_transaction || block
+          raise ArgumentError, "a transaction must be provided or defined in a block"
+        end
+
+        other_transaction || DSL.new(**options, &block).call
+      end
+    end
+  end
+end