transflow 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3dde7fc2cfdb940553b3a4ddabe1004d01ca49a6
-  data.tar.gz: 2c7b0e6c01338cd5087ac5dc332e9c5936d3a5b5
+  metadata.gz: e56210712ab5748639ce2feb57913c5754102588
+  data.tar.gz: 7823b8b50bf6f6d258ca2ee787585341b9a72ca9
 SHA512:
-  metadata.gz: c4601d2a9a7a8dfd1d72c03199f696483fa1de7bf66f0e398cecd17115bbf6a54333c32c11740ec2998d7626bbb8dadc3aab9088b4ed580f0a71cd2bd0af803d
-  data.tar.gz: f0ccebb883cc983ace244989008a23c649e2b234ced17692923747c95d6be1b185a4528d5e64202fdf71e829b94f5162ffb3e08611eb05286556a4865b1e5b47
+  metadata.gz: 1dba14fc104d96601b42e7a73abbfcba85a2b3e7f67eb33b2863f129a6ade75bfc025e5750b2749e342f5078ea5a950aba5ee76182ca7696f7a4f4028701a1c5
+  data.tar.gz: 0da536341a6345f6205a5db977d57be6c1a0e8f1ae94e4d51c2494487751a67fa85ad3421f0832c32ad7fe1653a184e05392cb8f10cbcb43948260ca8fd63dd8

data/CHANGELOG.md

@@ -1,3 +1,32 @@
+# 0.1.0 2015-08-17
+
+## Added
+
+- `Transaction#call` will raise if options include an unknown step name (solnic)
+- `Transflow` support shorter syntax for steps: `steps :one, :two, :three` (solnic)
+- `step(name)` defaults to `step(name, with: name)` (solnic)
+
+## Fixed
+
+- `Transaction#to_s` displays steps in the order of execution (solnic)
+
+## Internal
+
+- Organize source code into separate files (solnic)
+- Document public interface with YARD (solnic)
+- Add unit specs for `Transaction` (solnic)
+
+[Compare v0.0.2...v0.1.0](https://github.com/solnic/transflow/compare/v0.0.2...v0.1.0)
+
+# 0.0.2 2015-08-16
+
+## Added
+
+- Ability to pass aditional arguments to specific operations prior calling the
+  whole transaction (solnic)
+
+[Compare v0.0.2...v0.0.2](https://github.com/solnic/transflow/compare/v0.0.1...v0.0.2)
+
 # 0.0.2 2015-08-16
 
 ## Added
@@ -5,7 +34,7 @@
 - Ability to publish events from operations via `publish: true` option (solnic)
 - Ability to subscribe to events via `Transflow::Transaction#subscribe` interface (solnic)
 
-[Compare v0.0.1...v0.0.2](https://github.com/rom-rb/rom/compare/v0.0.1...v0.0.2)
+[Compare v0.0.1...v0.0.2](https://github.com/solnic/transflow/compare/v0.0.1...v0.0.2)
 
 # 0.0.1 2015-08-16
 

data/README.md

@@ -30,8 +30,8 @@ It is based on the following ideas:
   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
-- each operation can broadcast its result (TODO)
-- external message consumers can listen to a transaction object for specific events (TODO)
+- each operation can broadcast its result
+- external message consumers can listen to a transaction object for specific events
 
 ## Why?
 
@@ -53,33 +53,46 @@ error listener that can simply gather errors and return it as a result.
 
 ## Synopsis
 
+Using Transflow is ridiculously simple as it doesn't make much assumptions about
+your code. You provide container with operations and they simply need to respond
+to `#call(input)` and return output or raise an error if something went wrong.
+
+### Defining a simple flow
+
 ``` ruby
 DB = []
 
 container = {
-  validate: -> input { raise "name nil" if input[:name].nil? },
+  validate: -> input { input[:name].nil? ? raise("name nil") : input  },
   persist: -> input { DB << input[:name] }
 }
 
-my_business_flow = Transflow(container: container) do
-  step(:validate) { step(:persist) }
-end
+my_business_flow = Transflow(container: container) { steps :validate, :persist }
 
 my_business_flow[{ name: 'Jane' }]
 
 puts DB.inspect
 # ["Jane"]
+```
+
+## Defining a flow with event publishers
+
+In many cases an individual operation may require additional behavior to be
+triggered. This can be easily achieved with a pub/sub mechanism. Transflow
+provides that mechanism through the wonderful `wisper` gem which is used under
+the hood.
 
-## The same but with events
+``` ruby
+DB = []
 
-NOTIFICATIONS = []
+NOTIFICATIONS = [] # just for the sake of the example
 
-class Notify
-  def persist_success(user)
+class UserPersistListener
+  def self.persist_success(user)
     NOTIFICATIONS << "#{user} persisted"
   end
 
-  def persist_failure(user, err)
+  def self.persist_failure(user, err)
     # do sth about that
   end
 end
@@ -88,9 +101,7 @@ my_business_flow = Transflow(container: container) do
   step(:validate) { step(:persist, publish: true) }
 end
 
-notify = Notify.new
-
-my_business_flow.subscribe(persist: notify)
+my_business_flow.subscribe(persist: UserPersistListener)
 
 my_business_flow[{ name: 'Jane' }]
 
@@ -101,6 +112,41 @@ puts NOTIFICATIONS.inspect
 # ["Jane persisted"]
 ```
 
+### Passing additional arguments
+
+Another common requirement is to pass aditional arguments that we don't have in
+the moment of defining our flow. Fortunately Transflow allows you to pass any
+arguments in the moment you call the transaction. Those arguments will be curried
+which means you must use either procs as your operation or an object that responds
+to `curry`. This limitation will be removed soon.
+
+``` ruby
+DB = []
+
+operations = {
+  preprocess_input: -> input { { name: input['name'], email: input['email'] } },
+  # let's say this one needs additional argument called `email`
+  validate_input: -> email, input { input[:email] == email ? input : raise('ops') },
+  persist_input: -> input { DB << input[:name] }
+}
+
+transflow = Transflow(container: operations) do
+  step :preprocess, with: :preprocess_input do
+    step :validate, with: :validate_input do
+      step :persist, with: :persist_input
+    end
+  end
+end
+
+input = { 'name' => 'Jane', 'email' => 'jane@doe.org' }
+
+# here we say "for `validate` operation curry this additional argument
+transflow[input, validate: 'jane@doe.org']
+
+puts DB.inspect
+# ["Jane"]
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -117,10 +163,6 @@ Or install it yourself as:
 
     $ gem install transflow
 
-## Usage
-
-TODO: Write usage instructions here
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -129,4 +171,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/transflow.
+Bug reports and pull requests are welcome on GitHub at https://github.com/solnic/transflow.

data/lib/transflow.rb

@@ -1,10 +1,21 @@
 require 'transflow/version'
 require 'transflow/flow_dsl'
 
-# Define a transaction flow
+# Define a business transaction flow.
 #
-# @example
+# A business transaction flow is a simple composition of callable objects that
+# receive an input and produce an output. Steps are registered in the same order
+# they are defined within the DSL and that's also the order of execution.
+#
+# Initial input is sent to the first step, its output is sent to the second step
+# and so on.
 #
+# Every step can become a publisher, which means you can broadcast results from
+# any step and subscribe event listeners to individual steps. This gives you
+# a flexible way of responding to successful or failed execution of individual
+# steps.
+#
+# @example
 #   container = { do_one: some_obj, do_two: some_obj }
 #
 #   my_business_flow = Transflow(container: container) do
@@ -13,6 +24,22 @@ require 'transflow/flow_dsl'
 #
 #   my_business_flow[some_input]
 #
+#   # with events
+#
+#   my_business_flow = Transflow(container: container) do
+#     step(:one, with: :do_one) { step(:two, with: :do_two, publish: true) }
+#   end
+#
+#   class Listener
+#     def self.do_two_success(*args)
+#       puts ":do_two totally worked and produced: #{args.inspect}!"
+#     end
+#   end
+#
+#   my_business_flow.subscribe(do_two: Listener)
+#
+#   my_business_flow[some_input]
+#
 # @options [Hash] options The option hash
 #
 # @api public

data/lib/transflow/flow_dsl.rb

@@ -1,45 +1,39 @@
-require 'transproc'
-
 require 'transflow/step_dsl'
 require 'transflow/transaction'
 
 module Transflow
+  # @api private
   class FlowDSL
-    module Registry
-      extend Transproc::Registry
-    end
-
-    def self.[](op)
-      if op.respond_to?(:>>)
-        op
-      else
-        Registry[op]
-      end
-    end
-
+    # @api private
     attr_reader :options
 
+    # @api private
     attr_reader :container
 
-    attr_reader :steps
+    # @api private
+    attr_reader :step_map
 
+    # @api private
     def initialize(options, &block)
       @options = options
       @container = options.fetch(:container)
-      @steps = {}
+      @step_map = {}
       instance_exec(&block)
     end
 
-    def step(*args, &block)
-      StepDSL.new(*args, container, steps, &block).call
+    # @api private
+    def steps(*names)
+      names.reverse_each { |name| step(name) }
     end
 
-    def call
-      Transaction.new(steps, operations.reduce(:>>))
+    # @api private
+    def step(name, options = {}, &block)
+      StepDSL.new(name, options, container, step_map, &block).call
     end
 
-    def operations
-      steps.values.reverse.map { |op| self.class[op] }
+    # @api private
+    def call
+      Transaction.new(step_map)
     end
   end
 end

data/lib/transflow/step_dsl.rb

@@ -14,7 +14,7 @@ module Transflow
 
     def initialize(name, options, container, steps, &block)
       @name = name
-      @handler = options.fetch(:with)
+      @handler = options.fetch(:with, name)
       @publish = options.fetch(:publish, false)
       @container = container
       @steps = steps

data/lib/transflow/transaction.rb

@@ -1,3 +1,5 @@
+require 'transproc'
+
 module Transflow
   class TransactionFailedError < StandardError
     attr_reader :transaction
@@ -8,35 +10,161 @@ module Transflow
       @transaction = transaction
       @original_error = original_error
 
-      super("#{transaction} failed")
+      super("#{transaction} failed [#{original_error.class}: #{original_error.message}]")
 
       set_backtrace(original_error.backtrace)
     end
   end
 
+  # Transaction encapsulates calling individual steps registered within a transflow
+  # constructor.
+  #
+  # It's responsible for calling steps in the right order and optionally currying
+  # arguments for specific steps.
+  #
+  # Furthermore you can subscribe event listeners to individual steps within a
+  # transaction.
+  #
+  # @api public
   class Transaction
-    attr_reader :handler
+    # Internal function factory using Transproc extension
+    #
+    # @api private
+    module Registry
+      extend Transproc::Registry
+    end
 
+    # @attr_reader [Hash<Symbol => Proc,#call>] steps The step map
+    #
+    # @api private
     attr_reader :steps
 
-    def initialize(steps, handler)
+    # @attr_reader [Array<Symbol>] step_names The names of registered steps
+    #
+    # @api private
+    attr_reader :step_names
+
+    # @api private
+    def initialize(steps)
       @steps = steps
-      @handler = handler
+      @step_names = steps.keys.reverse
     end
 
+    # Subscribe event listeners to specific steps
+    #
+    # @example
+    #   transaction = Transflow(container: my_container) {
+    #     step(:one) { step(:two, publish: true }
+    #   }
+    #
+    #   class MyListener
+    #     def self.two_success(*args)
+    #       puts 'yes!'
+    #     end
+    #
+    #     def self.two_failure(*args)
+    #       puts 'oh noez!'
+    #     end
+    #   end
+    #
+    #   transaction.subscribe(two: my_listener)
+    #
+    #   transaction.call(some_input)
+    #
+    # @param [Hash<Symbol => Object>] listeners The step=>listener map
+    #
+    # @return [self]
+    #
+    # @api public
     def subscribe(listeners)
       listeners.each { |step, listener| steps[step].subscribe(listener) }
+      self
     end
 
-    def call(*args)
-      handler.call(*args)
+    # Call the transaction
+    #
+    # Once transaction is called it will call the first step and its result
+    # will be passed to the second step and so on.
+    #
+    # @example
+    #   my_container = {
+    #     add_one: -> i { i + 1 },
+    #     add_two: -> j { j + 2 }
+    #   }
+    #
+    #   transaction = Transflow(container: my_container) {
+    #     step(:one, with: :add_one) { step(:two, with: :add_two) }
+    #   }
+    #
+    #   transaction.call(1) # 4
+    #
+    # @param [Object] input The input for the first step
+    #
+    # @param [Hash] options The curry-args map, optional
+    #
+    # @return [Object]
+    #
+    # @raises TransactionFailedError
+    #
+    # @api public
+    def call(input, options = {})
+      handler = handler_steps(options).map(&method(:fn)).reduce(:>>)
+      handler.call(input)
     rescue Transproc::MalformedInputError => err
-      raise TransactionFailedError.new(self, err)
+      raise TransactionFailedError.new(self, err.original_error)
     end
     alias_method :[], :call
 
+    # Coerce a transaction into string representation
+    #
+    # @return [String]
+    #
+    # @api public
     def to_s
-      "Transaction(#{steps.keys.join(' => ')})"
+      "Transaction(#{step_names.join(' => ')})"
+    end
+
+    private
+
+    # @api private
+    def handler_steps(options)
+      if options.any?
+        assert_valid_options(options)
+
+        steps.map { |(name, op)|
+          args = options[name]
+
+          if args
+            op.curry.call(args)
+          else
+            op
+          end
+        }
+      else
+        steps.values
+      end.reverse
+    end
+
+    # @api private
+    def assert_valid_options(options)
+      options.each_key do |name|
+        unless step_names.include?(name)
+          raise ArgumentError, "+#{name}+ is not a valid step name"
+        end
+      end
+    end
+
+    # Wrap a proc into composable transproc function
+    #
+    # @param [#call]
+    #
+    # @api private
+    def fn(obj)
+      if obj.respond_to?(:>>)
+        obj
+      else
+        Registry[obj]
+      end
     end
   end
 end

data/lib/transflow/version.rb

@@ -1,3 +1,3 @@
 module Transflow
-  VERSION = '0.0.2'.freeze
+  VERSION = '0.1.0'.freeze
 end

data/transflow.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency 'transproc', '~> 0.3', '>= 0.3.1'
+  spec.add_runtime_dependency 'transproc', '~> 0.3', '>= 0.3.2'
   spec.add_runtime_dependency 'wisper'
 
   spec.add_development_dependency "bundler", "~> 1.10"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: transflow
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Piotr Solnica
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-08-16 00:00:00.000000000 Z
+date: 2015-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: transproc
@@ -19,7 +19,7 @@ dependencies:
         version: '0.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.1
+        version: 0.3.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,7 @@ dependencies:
         version: '0.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.1
+        version: 0.3.2
 - !ruby/object:Gem::Dependency
   name: wisper
   requirement: !ruby/object:Gem::Requirement