call_sheet 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 22cdd99caebdca48c7f1af8c352946c346de879a
-  data.tar.gz: 9330dd2494ced730459a53e810ac1076dd66f162
+  metadata.gz: 04addbea6823e48be8a177f6ed780599763e6e60
+  data.tar.gz: 0b8fc7f7227ee2b2deb80d5c480738d9a6c2968f
 SHA512:
-  metadata.gz: 44a856b644c6e36dc2cf8a29e724f1d1c03a9263eb43b8be7f9fc042429e7b58d57d865d87a45e61ec4a587515f93c76719bf0997a7f6148fdb3c40aaa5a631e
-  data.tar.gz: bfc12f1e07ea2783c8a4fe52e364593148de4f56c21f695582c7dfef14d6ef525b9270099231fccddb55610b35c3ae8ea0f570c50fb65839505104d9ce67dd8a
+  metadata.gz: ff2fae39de04d6840acfba7b5f802b0b018eb108e4e2eee2de3c536b53adad1220d382091cfc9059f1b08d1b1e1bd459f7b6cb971e6f56f0b817cf49c23a899f
+  data.tar.gz: e5b423a612353fcdc38ffe7b0a7904a2848da73ab78e9242092e124cc8841622d9408aa98d910f535509185cc464248d679510cd15671d5313cdf2498c2e39a5

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    call_sheet (0.3.1)
+    call_sheet (0.4.0)
       kleisli
       wisper (>= 1.6.0)
 

data/README.md

@@ -1,8 +1,9 @@
+[gitter]: https://gitter.im/icelab/call_sheet?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
 [gem]: https://rubygems.org/gems/call_sheet
 [code_climate]: https://codeclimate.com/github/icelab/call_sheet
 [inch]: http://inch-ci.org/github/icelab/call_sheet
 
-# Call Sheet
+# Call Sheet [![Join the chat at https://gitter.im/icelab/call_sheet](https://badges.gitter.im/Join%20Chat.svg)](gitter)
 
 [![Gem Version](https://img.shields.io/gem/v/call_sheet.svg)][gem]
 [![Code Climate](https://img.shields.io/codeclimate/github/icelab/call_sheet.svg)][code_climate]
@@ -23,35 +24,53 @@ Call Sheet is based on the following ideas, drawn mostly from [Transflow](http:/
 
 ## Why?
 
-Requiring a business transaction's steps to exist as independent operations directly addressable voa 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.
+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
 
-All you need to use Call Sheet is a container of operations that respond to `#call(input)`. The operations will be resolved from the container via `#[]`. The examples below use a plain Hash for simplicity, but for a larger app you may like to consider something like [dry-container](https://github.com/dryrb/dry-container).
+### Container
 
-Each operation is integrated into your business transaction through one of the following step adapters:
+All you need to use Call Sheet is a container to hold your application’s operations. Each operation must respond to `#call(input)`.
 
-* `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)`.
-* `raw` or `step` – the operation already returns its own `Either` object, and needs no special handling.
+The operations will be resolved from the container via `#[]`. For our examples, we’ll use a plain hash:
 
 ```ruby
-DB = []
-
 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 = CallSheet(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"})
@@ -60,7 +79,7 @@ DB
 # => [{:name=>"Jane", :email=>"jane@doe.com"}]
 ```
 
-Each transaction returns a result value wrapped in a `Left` or `Right` object. You can handle these different results (including errors arising from particular steps) with a match block:
+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|
@@ -139,6 +158,10 @@ NOTIFICATIONS
 
 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/icelab/call_sheet/CallSheet/Transaction) 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:
@@ -151,8 +174,6 @@ save_user = CallSheet(container: large_whole_app_container) do
 end
 ```
 
-A `raw` step (also aliased as `step`) can be used if the operation in your container already returns an `Either` and therefore doesn’t need any special handling.
-
 ## Installation
 
 Add this line to your application’s `Gemfile`:
@@ -163,6 +184,10 @@ gem "call_sheet"
 
 Run `bundle` to install the gem.
 
+## Documentation
+
+View the [full API documentation](http://www.rubydoc.info/github/icelab/call_sheet) on RubyDoc.info.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on [GitHub](http://github.com/icelab/call_sheet).

data/lib/call_sheet.rb

@@ -12,25 +12,24 @@ require "call_sheet/dsl"
 # `#call(*args, input)`.
 #
 # Each operation will be called in the order it was specified in your
-# transaction, with its output is passed as the intput to the next operation.
+# 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 `Success` object (from the
-# [Deterministic](deterministic) gem) wrapping its output value. A step is a
-# failure when it returns a `Failure` object.  If your operations already
-# return a `Success` or `Failure`, they can be added to your operation as
-# plain `step` or `raw` steps.
+# 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 `Success` or `Failure`, then they
-# can be added to the transaction with the following 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 `Success`
-# * `try` --- wrap the output of the operation in a `Success`, unless a certain
-#   exception is raised, which will be caught and returned as a `Failure`.
+# * `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 `Sucess`.
+#   input as a `Right`.
 #
-# [deterministic]: https://github.com/pzol/deterministic
+# [kleisli]: https://rubygems.org/gems/kleisli
 #
 # @example
 #   container = {do_first: some_obj, do_second: some_obj}
@@ -42,7 +41,7 @@ require "call_sheet/dsl"
 #
 #   my_transaction.call(some_input)
 #
-# @param [Hash] options the options hash
+# @param options [Hash] the options hash
 # @option options [#[]] :container the operations container
 #
 # @return [CallSheet::Transaction] the transaction object

data/lib/call_sheet/result_matcher.rb

@@ -1,39 +1,23 @@
 module CallSheet
   class ResultMatcher
     attr_reader :result
-    attr_reader :value
+    attr_reader :output
 
     def initialize(result)
       @result = result
-      @value = result.value
     end
 
     def success(&block)
-      block.call value if result.is_a?(Kleisli::Either::Right)
-    end
+      return output unless result.is_a?(Kleisli::Either::Right)
 
-    def failure(&block)
-      block.call FailureMatcher.new(result) if result.is_a?(Kleisli::Either::Left)
+      @output = block.call(result.value)
     end
 
-    class FailureMatcher
-      attr_reader :result
-      attr_reader :value
-
-      def initialize(result)
-        @result = result
-        @value = result.value
-      end
-
-      def on(step_name, &block)
-        if value.__step_name == step_name
-          @matched = true
-          block.call value
-        end
-      end
+    def failure(step_name = nil, &block)
+      return output unless result.is_a?(Kleisli::Either::Left)
 
-      def otherwise(&block)
-        block.call value unless @matched
+      if step_name.nil? || step_name == result.value.__step_name
+        @output = block.call(result.value)
       end
     end
   end

data/lib/call_sheet/step_adapters/raw.rb

@@ -8,6 +8,5 @@ module CallSheet
     end
 
     register :step, Raw
-    register :raw, Raw
   end
 end

data/lib/call_sheet/transaction.rb

@@ -4,13 +4,39 @@ module CallSheet
   class Transaction
     # @api private
     attr_reader :steps
-    private :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)
@@ -19,11 +45,40 @@ module CallSheet
       steps = steps_with_options_applied(options)
       result = steps.inject(Right(input), :>>)
 
-      block.call ResultMatcher.new(result) if block
-      result
+      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)
@@ -39,6 +94,163 @@ module CallSheet
       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 = CallSheet(container: container) do
+    #     step :first
+    #     step :second
+    #   end
+    #
+    #   other_transaction = CallSheet(container: container) do
+    #     step :another
+    #   end
+    #
+    #   my_transaction.prepend(other_transaction)
+    #
+    # @example Prepend a transaction defined inline
+    #   my_transaction = CallSheet(container: container) do
+    #     step :first
+    #     step :second
+    #   end
+    #
+    #   my_transaction.prepend(container: container) do
+    #     step :another
+    #   end
+    #
+    # @param other [CallSheet::Transaction] 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 [CallSheet::Transaction] 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 = CallSheet(container: container) do
+    #     step :first
+    #     step :second
+    #   end
+    #
+    #   other_transaction = CallSheet(container: container) do
+    #     step :another
+    #   end
+    #
+    #   my_transaction.append(other_transaction)
+    #
+    # @example Append a transaction defined inline
+    #   my_transaction = CallSheet(container: container) do
+    #     step :first
+    #     step :second
+    #   end
+    #
+    #   my_transaction.append(container: container) do
+    #     step :another
+    #   end
+    #
+    # @param other [CallSheet::Transaction] 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 [CallSheet::Transaction] 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 = CallSheet(container: container) do
+    #     step :first
+    #     step :second
+    #   end
+    #
+    #   other_transaction = CallSheet(container: container) do
+    #     step :another
+    #   end
+    #
+    #   my_transaction.insert(other_transaction, before: :second)
+    #
+    # @example Append a transaction defined inline (after a step)
+    #   my_transaction = CallSheet(container: container) do
+    #     step :first
+    #     step :second
+    #   end
+    #
+    #   my_transaction.insert(after: :first, container: container) do
+    #     step :another
+    #   end
+    #
+    # @param other [CallSheet::Transaction] 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 [CallSheet::Transaction] 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 = CallSheet(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 [CallSheet::Transaction] 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)
@@ -69,5 +281,13 @@ module CallSheet
         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

data/lib/call_sheet/version.rb

@@ -1,4 +1,4 @@
 # Business transaction DSL.
 module CallSheet
-  VERSION = "0.3.2".freeze
+  VERSION = "0.4.0".freeze
 end

data/spec/examples.txt

@@ -1,23 +1,41 @@
 example_id                                               | status | run_time        |
 -------------------------------------------------------- | ------ | --------------- |
-./spec/integration/call_sheet_spec.rb[1:1:1]             | passed | 0.00146 seconds |
-./spec/integration/call_sheet_spec.rb[1:1:2]             | passed | 0.00022 seconds |
+./spec/integration/call_sheet_spec.rb[1:1:1]             | passed | 0.00106 seconds |
+./spec/integration/call_sheet_spec.rb[1:1:2]             | passed | 0.00021 seconds |
 ./spec/integration/call_sheet_spec.rb[1:1:3]             | passed | 0.00019 seconds |
-./spec/integration/call_sheet_spec.rb[1:1:4]             | passed | 0.00028 seconds |
-./spec/integration/call_sheet_spec.rb[1:1:5]             | passed | 0.00104 seconds |
-./spec/integration/call_sheet_spec.rb[1:2:1]             | passed | 0.00206 seconds |
-./spec/integration/call_sheet_spec.rb[1:2:2]             | passed | 0.00023 seconds |
-./spec/integration/call_sheet_spec.rb[1:2:3]             | passed | 0.00022 seconds |
-./spec/integration/call_sheet_spec.rb[1:2:4]             | passed | 0.00022 seconds |
-./spec/integration/call_sheet_spec.rb[1:2:5]             | passed | 0.00022 seconds |
-./spec/integration/call_sheet_spec.rb[1:2:6]             | passed | 0.00032 seconds |
-./spec/integration/call_sheet_spec.rb[1:3:1]             | passed | 0.00019 seconds |
-./spec/integration/call_sheet_spec.rb[1:3:2]             | passed | 0.00016 seconds |
-./spec/integration/call_sheet_spec.rb[1:3:3]             | passed | 0.00017 seconds |
-./spec/integration/passing_step_arguments_spec.rb[1:1:1] | passed | 0.00113 seconds |
-./spec/integration/passing_step_arguments_spec.rb[1:2:1] | passed | 0.0002 seconds  |
-./spec/integration/passing_step_arguments_spec.rb[1:3:1] | passed | 0.00221 seconds |
-./spec/integration/publishing_step_events_spec.rb[1:1:1] | passed | 0.00194 seconds |
-./spec/integration/publishing_step_events_spec.rb[1:1:2] | passed | 0.00042 seconds |
-./spec/integration/publishing_step_events_spec.rb[1:2:1] | passed | 0.00032 seconds |
-./spec/integration/publishing_step_events_spec.rb[1:2:2] | passed | 0.00027 seconds |
+./spec/integration/call_sheet_spec.rb[1:1:4]             | passed | 0.00033 seconds |
+./spec/integration/call_sheet_spec.rb[1:1:5]             | passed | 0.00021 seconds |
+./spec/integration/call_sheet_spec.rb[1:2:1]             | passed | 0.00153 seconds |
+./spec/integration/call_sheet_spec.rb[1:2:2]             | passed | 0.00052 seconds |
+./spec/integration/call_sheet_spec.rb[1:2:3]             | passed | 0.00021 seconds |
+./spec/integration/call_sheet_spec.rb[1:2:4]             | passed | 0.00024 seconds |
+./spec/integration/call_sheet_spec.rb[1:2:5]             | passed | 0.00023 seconds |
+./spec/integration/call_sheet_spec.rb[1:2:6]             | passed | 0.00023 seconds |
+./spec/integration/call_sheet_spec.rb[1:3:1]             | passed | 0.00022 seconds |
+./spec/integration/call_sheet_spec.rb[1:3:2]             | passed | 0.00017 seconds |
+./spec/integration/call_sheet_spec.rb[1:3:3]             | passed | 0.00018 seconds |
+./spec/integration/passing_step_arguments_spec.rb[1:1:1] | passed | 0.00037 seconds |
+./spec/integration/passing_step_arguments_spec.rb[1:2:1] | passed | 0.00026 seconds |
+./spec/integration/passing_step_arguments_spec.rb[1:3:1] | passed | 0.00026 seconds |
+./spec/integration/publishing_step_events_spec.rb[1:1:1] | passed | 0.00134 seconds |
+./spec/integration/publishing_step_events_spec.rb[1:1:2] | passed | 0.00051 seconds |
+./spec/integration/publishing_step_events_spec.rb[1:2:1] | passed | 0.00039 seconds |
+./spec/integration/publishing_step_events_spec.rb[1:2:2] | passed | 0.00035 seconds |
+./spec/unit/transaction_spec.rb[1:1:1]                   | passed | 0.00014 seconds |
+./spec/unit/transaction_spec.rb[1:1:2]                   | passed | 0.00028 seconds |
+./spec/unit/transaction_spec.rb[1:1:3]                   | passed | 0.00013 seconds |
+./spec/unit/transaction_spec.rb[1:1:4]                   | passed | 0.00013 seconds |
+./spec/unit/transaction_spec.rb[1:2:1]                   | passed | 0.00018 seconds |
+./spec/unit/transaction_spec.rb[1:2:2]                   | passed | 0.00079 seconds |
+./spec/unit/transaction_spec.rb[1:2:3]                   | passed | 0.00145 seconds |
+./spec/unit/transaction_spec.rb[1:2:4]                   | passed | 0.00014 seconds |
+./spec/unit/transaction_spec.rb[1:3:1]                   | passed | 0.00022 seconds |
+./spec/unit/transaction_spec.rb[1:3:2]                   | passed | 0.00016 seconds |
+./spec/unit/transaction_spec.rb[1:4:1]                   | passed | 0.00036 seconds |
+./spec/unit/transaction_spec.rb[1:4:2]                   | passed | 0.00017 seconds |
+./spec/unit/transaction_spec.rb[1:4:3]                   | passed | 0.00013 seconds |
+./spec/unit/transaction_spec.rb[1:4:4]                   | passed | 0.00012 seconds |
+./spec/unit/transaction_spec.rb[1:4:5:1]                 | passed | 0.00018 seconds |
+./spec/unit/transaction_spec.rb[1:4:5:2]                 | passed | 0.00031 seconds |
+./spec/unit/transaction_spec.rb[1:4:6:1]                 | passed | 0.00021 seconds |
+./spec/unit/transaction_spec.rb[1:4:6:2]                 | passed | 0.00021 seconds |

data/spec/integration/call_sheet_spec.rb

@@ -2,7 +2,7 @@ RSpec.describe CallSheet do
   let(:call_sheet) {
     CallSheet(container: container) do
       map :process
-      raw :verify
+      step :verify
       try :validate, catch: Test::NotValidError
       tee :persist
     end
@@ -79,8 +79,8 @@ RSpec.describe CallSheet do
       results = []
 
       call_sheet.call(input) do |m|
-        m.failure do |f|
-          results << "Failed: #{f.value}"
+        m.failure do |value|
+          results << "Failed: #{value}"
         end
       end
 
@@ -91,10 +91,8 @@ RSpec.describe CallSheet do
       results = []
 
       call_sheet.call(input) do |m|
-        m.failure do |f|
-          f.on :validate do |v|
-            results << "Validation failure: #{v}"
-          end
+        m.failure :validate do |value|
+          results << "Validation failure: #{value}"
         end
       end
 
@@ -105,14 +103,12 @@ RSpec.describe CallSheet do
       results = []
 
       call_sheet.call(input) do |m|
-        m.failure do |f|
-          f.on :some_other_step do |v|
-            results << "Some other step failure"
-          end
-
-          f.otherwise do |v|
-            results << "Catch-all failure: #{v}"
-          end
+        m.failure :some_other_step do |value|
+          results << "Some other step failure"
+        end
+
+        m.failure do |value|
+          results << "Catch-all failure: #{value}"
         end
       end
 

data/spec/integration/publishing_step_events_spec.rb

@@ -2,7 +2,7 @@ RSpec.describe "publishing step events" do
   let(:call_sheet) {
     CallSheet(container: container) do
       map :process
-      raw :verify
+      step :verify
       tee :persist
     end
   }

data/spec/unit/transaction_spec.rb

@@ -0,0 +1,173 @@
+RSpec.describe CallSheet::Transaction do
+  subject(:container) {
+    {
+      upcase: -> input { input.upcase },
+      reverse: -> input { input.reverse },
+      exclaim_all: -> input { input.split(" ").map { |str| str + "!" }.join(" ") },
+    }
+  }
+
+  describe "#prepend" do
+    let(:initial_transaction) {
+      CallSheet(container: container) do
+        map :exclaim_all
+      end
+    }
+
+    it "prepends the transaction" do
+      other_transaction = CallSheet(container: container) do
+        map :reverse
+      end
+      new_transaction = initial_transaction.prepend(other_transaction)
+
+      expect(new_transaction.call("hello world").right).to eq "dlrow! olleh!"
+    end
+
+    it "accepts a transaction defined in a block" do
+      new_transaction = initial_transaction.prepend(container: container) do
+        map :reverse
+      end
+
+      expect(new_transaction.call("hello world").right).to eq "dlrow! olleh!"
+    end
+
+    it "raises an argument error if a transaction is neither passed nor defined" do
+      expect { initial_transaction.prepend }.to raise_error(ArgumentError)
+    end
+
+    it "leaves the original transaction unmodified" do
+      new_transaction = initial_transaction.prepend(container: container) do
+        map :reverse
+      end
+
+      expect(initial_transaction.call("the quick brown fox").right).to eq "the! quick! brown! fox!"
+    end
+  end
+
+  describe "#append" do
+    let(:initial_transaction) {
+      CallSheet(container: container) do
+        map :exclaim_all
+      end
+    }
+
+    it "appends the transaction" do
+      other_transaction = CallSheet(container: container) do
+        map :reverse
+      end
+      new_transaction = initial_transaction.append(other_transaction)
+
+      expect(new_transaction.call("hello world").right).to eq "!dlrow !olleh"
+    end
+
+    it "accepts a transaction defined in a block" do
+      new_transaction = initial_transaction.append(container: container) do
+        map :reverse
+      end
+
+      expect(new_transaction.call("hello world").right).to eq "!dlrow !olleh"
+    end
+
+    it "raises an argument error if a transaction is neither passed nor defined" do
+      expect { initial_transaction.insert(before: :reverse) }.to raise_error(ArgumentError)
+    end
+
+    it "leaves the original transaction unmodified" do
+      new_transaction = initial_transaction.append(container: container) do
+        map :reverse
+      end
+
+      expect(initial_transaction.call("hello world").right).to eq "hello! world!"
+    end
+  end
+
+  describe "#remove" do
+    let(:initial_transaction) {
+      CallSheet(container: container) do
+        map :upcase
+        map :exclaim_all
+        map :reverse
+      end
+    }
+
+    it "removes the specified steps" do
+      new_transaction = initial_transaction.remove(:exclaim_all, :reverse)
+      expect(new_transaction.call("hello world").right).to eq "HELLO WORLD"
+    end
+
+    it "leaves the original transaction unmodified" do
+      new_transaction = initial_transaction.remove(:exclaim_all, :reverse)
+      expect(initial_transaction.call("hello world").right).to eq "!DLROW !OLLEH"
+    end
+  end
+
+  describe "#insert" do
+    let(:initial_transaction) {
+      CallSheet(container: container) do
+        map :upcase
+        map :reverse
+      end
+    }
+
+    it "accepts a transaction passed as an argument" do
+      other_transaction = CallSheet(container: container) do
+        map :exclaim_all
+      end
+      new_transaction = initial_transaction.insert(other_transaction, before: :reverse)
+
+      expect(new_transaction.call("hello world").right).to eq "!DLROW !OLLEH"
+    end
+
+    it "accepts a transaction defined in a block" do
+      new_transaction = initial_transaction.insert(before: :reverse, container: container) do
+        map :exclaim_all
+      end
+
+      expect(new_transaction.call("hello world").right).to eq "!DLROW !OLLEH"
+    end
+
+    it "raises an argument error if a transaction is neither passed nor defined" do
+      expect { initial_transaction.insert(before: :reverse) }.to raise_error(ArgumentError)
+    end
+
+    it "raises an argument error if an invalid step name is provided" do
+      expect {
+        initial_transaction.insert(before: :non_existent, container: container) do
+          map :exclaim_all
+        end
+      }.to raise_error(ArgumentError)
+    end
+
+    context "before" do
+      let!(:new_transaction) {
+        initial_transaction.insert(before: :reverse, container: container) do
+          map :exclaim_all
+        end
+      }
+
+      it "inserts the new steps before the specified one" do
+        expect(new_transaction.call("hello world").right).to eq "!DLROW !OLLEH"
+      end
+
+      it "leaves the original transaction unmodified" do
+        expect(initial_transaction.call("hello world").right).to eq "DLROW OLLEH"
+      end
+    end
+
+    context "after" do
+      let!(:new_transaction) {
+        initial_transaction.insert(after: :reverse, container: container) do
+          map :exclaim_all
+        end
+      }
+
+      it "inserts the new steps after the specified one" do
+        expect(new_transaction.call("hello world").right).to eq "DLROW! OLLEH!"
+      end
+
+      it "leaves the original transaction unmodified" do
+        expect(initial_transaction.call("hello world").right).to eq "DLROW OLLEH"
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: call_sheet
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Tim Riley
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-11-13 00:00:00.000000000 Z
+date: 2015-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: kleisli
@@ -153,6 +153,7 @@ files:
 - spec/integration/publishing_step_events_spec.rb
 - spec/spec_helper.rb
 - spec/support/test_module_constants.rb
+- spec/unit/transaction_spec.rb
 homepage: https://github.com/icelab/call_sheet
 licenses:
 - MIT
@@ -165,7 +166,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="