transflow 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 191a70cd5a82b31910a2f10b64e5058ae376f729
-  data.tar.gz: d7ad841f948925604c5b0c176c86c66c9d4a05cf
+  metadata.gz: c021e3e6b56f1b856d4fe83400829b642a685fbc
+  data.tar.gz: c2462b4a2bcf77dc345c9fc847715ac626ca813d
 SHA512:
-  metadata.gz: c2c407713885bd8d348fbdbd6ea3c79547d82047dd20d989da5a83f3b7f1aba0134dacb1bffd57ba73385de1c13ab75735652659c99ca203118dafd888da110a
-  data.tar.gz: dc06637017c57a11ed654b1361490a98269aeeb1cb616751cc048b42ec67ea14195665b3582360889986605b69af8859224d4d073ce8b122de262c359fe71105
+  metadata.gz: 1f507660968d9a83111394311e18c1d2711019a6fb47801361cfc2cc7df5707336824cc77d53f355d3d7328a0b72662ae0b72949de37e453758ff71e1de5ff53
+  data.tar.gz: b9561cfc4d1cdc0091567aa367ebf03d783d3176b2e1a6cb18043e1cd43cb7fbaa39698b1cebc6b6f4777151d930a562f83b485bb4802f2d5d6d548a9922ab9a

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+# 0.3.0 2015-08-19
+
+## Added
+
+- Support for steps that return [kleisli](https://github.com/txus/kleisli) monads (solnic)
+- Support for setting default step options via flow DSL (solnic)
+- Support for subscribing many listeners to a single step (solnic)
+- Support for subscribing one listener to all steps (solnic)
+
+## Changed
+
+- Now step objects are wrapped using `Step` decorator that uses `dry-pipeline` gem (solnic)
+- Only `Transflow::StepError` errors can cause transaction failure (solnic)
+
+[Compare v0.2.0...v0.3.0](https://github.com/solnic/transflow/compare/v0.2.0...v0.3.0)
+
 # 0.2.0 2015-08-18
 
 ## Added

data/Gemfile

@@ -4,6 +4,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :test do
+  gem 'transproc'
   gem 'codeclimate-test-reporter', require: false, platforms: :rbx
 end
 

data/README.md

@@ -44,13 +44,6 @@ handled by a pub/sub interface.
 It's a clean and simple way of encapsulating complex business logic in your application
 using simple, stateless objects.
 
-## Error Handling
-
-This will be the tricky part - there are scenarios where we need to aggregate
-errors from multiple steps without stopping the processing. It's not implemented
-yet but *probably* using pub/sub for that will do the work as we can register an
-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
@@ -63,7 +56,7 @@ to `#call(input)` and return output or raise an error if something went wrong.
 DB = []
 
 container = {
-  validate: -> input { input[:name].nil? ? raise("name nil") : input  },
+  validate: -> input { input[:name].nil? ? raise(Transflow::StepError.new("name nil")) : input  },
   persist: -> input { DB << input[:name] }
 }
 
@@ -126,7 +119,7 @@ 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') },
+  validate_input: -> email, input { input[:email] == email ? input : raise(Transflow::StepError.new('ops')) },
   persist_input: -> input { DB << input[:name] }
 }
 
@@ -147,6 +140,44 @@ puts DB.inspect
 # ["Jane"]
 ```
 
+### Kleisli Integration
+
+You can use monads from [kleisli](https://github.com/txus/kleisli) gem in your
+steps to achieve a nice control-flow without exceptions:
+
+``` ruby
+
+DB = []
+
+validate = -> input do
+  if input[:email]
+    Right(input)
+  else
+    Left("what about the email?")
+  end
+end
+
+persist = -> input do
+  input.fmap do |values|
+    DB << values
+  end
+end
+
+container = { validate: validate, persist: persist }
+
+transflow = Transflow(container: container) do
+  monadic true
+
+  steps :validate, :persist
+end
+
+transflow[name: 'Jane', email: 'jane@doe.org']
+# Right([{:name=>"Jane", :email=>"jane@doe.org"}])
+
+transflow[name: 'Jane']
+# Left("what about the email?")
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/transflow/errors.rb

@@ -0,0 +1,30 @@
+module Transflow
+  class TransactionFailedError < StandardError
+    attr_reader :transaction
+
+    attr_reader :original_error
+
+    def initialize(transaction, original_error)
+      @transaction = transaction
+      @original_error = original_error
+
+      super("#{transaction} failed [#{original_error.class}: #{original_error.message}]")
+
+      set_backtrace(original_error.backtrace)
+    end
+  end
+
+  class StepError < StandardError
+    attr_reader :original_error
+
+    def initialize(input = nil)
+      if input.kind_of?(StandardError)
+        @original_error = input
+        super(@original_error.message)
+        set_backtrace(original_error.backtrace)
+      else
+        super(input)
+      end
+    end
+  end
+end

data/lib/transflow/flow_dsl.rb

@@ -13,22 +13,36 @@ module Transflow
     # @api private
     attr_reader :step_map
 
+    # @api private
+    attr_reader :step_options
+
     # @api private
     def initialize(options, &block)
       @options = options
       @container = options.fetch(:container)
       @step_map = {}
+      @step_options = {}
       instance_exec(&block)
     end
 
-    # @api private
+    # @api public
     def steps(*names)
       names.reverse_each { |name| step(name) }
     end
 
-    # @api private
+    # @api public
     def step(name, options = {}, &block)
-      StepDSL.new(name, options, container, step_map, &block).call
+      StepDSL.new(name, step_options.merge(options), container, step_map, &block).call
+    end
+
+    # @api public
+    def monadic(value)
+      step_options.update(monadic: value)
+    end
+
+    # @api public
+    def publish(value)
+      step_options.update(publish: value)
     end
 
     # @api private

data/lib/transflow/publisher.rb

@@ -1,4 +1,7 @@
 require 'wisper'
+require 'kleisli'
+
+require 'transflow/errors'
 
 module Transflow
   class Publisher
@@ -8,6 +11,24 @@ module Transflow
 
     attr_reader :op
 
+    def self.[](name, op, options = {})
+      type =
+        if options[:monadic]
+          Monadic
+        else
+          self
+        end
+      type.new(name, op)
+    end
+
+    class Monadic < Publisher
+      def call(*args)
+        op.(*args)
+          .or { |result| broadcast_failure(*args, result) and Left(result) }
+          .>-> value { broadcast_success(value) and Right(value) }
+      end
+    end
+
     class Curried < Publisher
       attr_reader :publisher
 
@@ -52,12 +73,25 @@ module Transflow
 
     def call(*args)
       result = op.call(*args)
-      broadcast(:"#{name}_success", result)
+      broadcast_success(result)
       result
-    rescue => err
-      broadcast(:"#{name}_failure", *args, err)
-      raise err
+    rescue StepError => err
+      broadcast_failure(*args, err) and raise(err)
     end
     alias_method :[], :call
+
+    def subscribe(listeners, *args)
+      Array(listeners).each { |listener| super(listener, *args) }
+    end
+
+    private
+
+    def broadcast_success(result)
+      broadcast(:"#{name}_success", result)
+    end
+
+    def broadcast_failure(*args, err)
+      broadcast(:"#{name}_failure", *args, err)
+    end
   end
 end

data/lib/transflow/step_dsl.rb

@@ -4,6 +4,8 @@ module Transflow
   class StepDSL
     attr_reader :name
 
+    attr_reader :options
+
     attr_reader :handler
 
     attr_reader :container
@@ -12,17 +14,21 @@ module Transflow
 
     attr_reader :publish
 
+    attr_reader :monadic
+
     def initialize(name, options, container, steps, &block)
       @name = name
+      @options = options
       @handler = options.fetch(:with, name)
       @publish = options.fetch(:publish, false)
+      @monadic = options.fetch(:monadic, false)
       @container = container
       @steps = steps
       instance_exec(&block) if block
     end
 
-    def step(*args, &block)
-      self.class.new(*args, container, steps, &block).call
+    def step(name, new_options = {}, &block)
+      self.class.new(name, options.merge(new_options), container, steps, &block).call
     end
 
     def call
@@ -30,7 +36,7 @@ module Transflow
 
       step =
         if publish
-          Publisher.new(name, operation)
+          Publisher[name, operation, monadic: monadic]
         else
           operation
         end

data/lib/transflow/transaction.rb

@@ -1,21 +1,7 @@
-require 'transproc'
+require 'dry-pipeline'
+require 'transflow/errors'
 
 module Transflow
-  class TransactionFailedError < StandardError
-    attr_reader :transaction
-
-    attr_reader :original_error
-
-    def initialize(transaction, original_error)
-      @transaction = transaction
-      @original_error = original_error
-
-      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.
   #
@@ -27,11 +13,20 @@ module Transflow
   #
   # @api public
   class Transaction
-    # Internal function factory using Transproc extension
+    # Step wrapper object which adds `>>` operator
     #
     # @api private
-    module Registry
-      extend Transproc::Registry
+    class Step
+      include Dry::Pipeline::Mixin
+
+      # @api private
+      def self.[](op)
+        if op.respond_to?(:>>)
+          op
+        else
+          Step.new(op)
+        end
+      end
     end
 
     # @attr_reader [Hash<Symbol => Proc,#call>] steps The step map
@@ -77,7 +72,11 @@ module Transflow
     #
     # @api public
     def subscribe(listeners)
-      listeners.each { |step, listener| steps[step].subscribe(listener) }
+      if listeners.is_a?(Hash)
+        listeners.each { |step, listener| steps[step].subscribe(listener) }
+      else
+        steps.each { |(_, step)| step.subscribe(listeners) }
+      end
       self
     end
 
@@ -108,10 +107,10 @@ module Transflow
     #
     # @api public
     def call(input, options = {})
-      handler = handler_steps(options).map(&method(:fn)).reduce(:>>)
+      handler = handler_steps(options).map(&method(:step)).reduce(:>>)
       handler.call(input)
-    rescue Transproc::MalformedInputError => err
-      raise TransactionFailedError.new(self, err.original_error)
+    rescue StepError => err
+      raise TransactionFailedError.new(self, err)
     end
     alias_method :[], :call
 
@@ -159,12 +158,8 @@ module Transflow
     # @param [#call]
     #
     # @api private
-    def fn(obj)
-      if obj.respond_to?(:>>)
-        obj
-      else
-        Registry[obj]
-      end
+    def step(obj)
+      Step[obj]
     end
   end
 end

data/lib/transflow/version.rb

@@ -1,3 +1,3 @@
 module Transflow
-  VERSION = '0.2.0'.freeze
+  VERSION = '0.3.0'.freeze
 end

data/transflow.gemspec

@@ -18,8 +18,9 @@ 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.2'
+  spec.add_runtime_dependency 'dry-pipeline'
   spec.add_runtime_dependency 'wisper'
+  spec.add_runtime_dependency 'kleisli'
 
   spec.add_development_dependency "bundler", "~> 1.10"
   spec.add_development_dependency "rake", "~> 10.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: transflow
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Piotr Solnica
@@ -11,25 +11,19 @@ cert_chain: []
 date: 2015-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: transproc
+  name: dry-pipeline
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.2
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.2
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: wisper
   requirement: !ruby/object:Gem::Requirement
@@ -44,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: kleisli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -104,6 +112,7 @@ files:
 - bin/console
 - bin/setup
 - lib/transflow.rb
+- lib/transflow/errors.rb
 - lib/transflow/flow_dsl.rb
 - lib/transflow/publisher.rb
 - lib/transflow/step_dsl.rb