flows 0.1.0 → 0.2.0

data/bin/benchmark

@@ -6,44 +6,62 @@ require 'benchmark/ips'
 
 require_relative './examples'
 
+with_all = ENV['WITH_ALL']
+
+with_railway = ENV['WITH_RW'] || with_all
+with_operation = ENV['WITH_OP'] || with_all
+with_dry = ENV['WITH_DRY'] || with_all
+with_trailblazer = ENV['WITH_TB'] || with_all
+
+with_poro = ENV['WITH_PORO']
+
+no_prebuild = ENV['NO_PREBUILD']
+no_eachbuild = ENV['NO_EACHBUILD']
+
+
 puts '-' * 50
 puts '- task: A + B, one step implementation'
 puts '-' * 50
 
 flows_summator = FlowsSummator.new
+flows_railway_summator = FlowsRailwaySummator.new
 dry_summator = DrySummator.new
 
 Benchmark.ips do |b|
-  b.report 'Flows::Operation (build each time)' do
-    FlowsSummator.new.call(a: 1, b: 2)
-  end
+  b.report 'Flows::Railway (build once)' do
+    flows_railway_summator.call(a: 1, b: 2)
+  end if with_railway && !no_prebuild
+
+  b.report 'Flows::Railway (build each time)' do
+    FlowsRailwaySummator.new.call(a: 1, b: 2)
+  end if with_railway && !no_eachbuild
 
   b.report 'Flows::Operation (build once)' do
     flows_summator.call(a: 1, b: 2)
-  end
+  end if with_operation && !no_prebuild
 
-  unless ENV['FLOWS_ONLY']
-    b.report 'Dry::Transaction (build each time)' do
-      DrySummator.new.call(a: 1, b: 2)
-    end
+  b.report 'Flows::Operation (build each time)' do
+    FlowsSummator.new.call(a: 1, b: 2)
+  end if with_operation && !no_eachbuild
+
+  b.report 'Dry::Transaction (build once)' do
+    dry_summator.call(a: 1, b: 2)
+  end if with_dry && !no_prebuild
 
-    b.report 'Dry::Transaction (build once)' do
-      dry_summator.call(a: 1, b: 2)
-    end
+  b.report 'Dry::Transaction (build each time)' do
+    DrySummator.new.call(a: 1, b: 2)
+  end if with_dry && !no_eachbuild
 
-    b.report 'Trailblazer::Operation' do
-      TBSummator.call(a: 1, b: 2)
-    end
-  end
+  b.report 'Trailblazer::Operation' do
+    TBSummator.call(a: 1, b: 2)
+  end if with_trailblazer
 
-  if ENV['WITH_PORO']
-    b.report 'PORO' do
-      POROSummator.call(a: 1, b: 2)
-    end
-  end
+  b.report 'PORO' do
+    POROSummator.call(a: 1, b: 2)
+  end if with_poro
 
   b.compare!
-end unless ENV['SKIP_SUM']
+end
 puts
 
 
@@ -52,37 +70,42 @@ puts '- task: ten steps returns successful result'
 puts '-' * 50
 
 flows_ten_steps = FlowsTenSteps.new
+flows_railway_ten_steps = FlowsRailwayTenSteps.new
 dry_ten_steps = DryTenSteps.new
 
 Benchmark.ips do |b|
-  b.report 'Flows::Operation (build each time)' do
-    FlowsTenSteps.new.call(a: 1, b: 2)
-  end
+  b.report 'Flows::Railway (build once)' do
+    flows_railway_ten_steps.call(a: 1, b: 2)
+  end if with_railway && !no_prebuild
+
+  b.report 'Flows::Railway (build each time)' do
+    FlowsRailwayTenSteps.new.call(a: 1, b: 2)
+  end if with_railway && !no_eachbuild
 
   b.report 'Flows::Operation (build once)' do
     flows_ten_steps.call(a: 1, b: 2)
-  end
+  end if with_operation && !no_prebuild
+
+  b.report 'Flows::Operation (build each time)' do
+    FlowsTenSteps.new.call(a: 1, b: 2)
+  end if with_operation && !no_eachbuild
 
-  unless ENV['FLOWS_ONLY']
-    b.report 'Dry::Transaction (build each time)' do
-      DryTenSteps.new.call(a: 1, b: 2)
-    end
+  b.report 'Dry::Transaction (build once)' do
+    dry_ten_steps.call(a: 1, b: 2)
+  end if with_dry && !no_prebuild
 
-    b.report 'Dry::Transaction (build once)' do
-      dry_ten_steps.call(a: 1, b: 2)
-    end
+  b.report 'Dry::Transaction (build each time)' do
+    DryTenSteps.new.call(a: 1, b: 2)
+  end if with_dry && !no_eachbuild
 
-    b.report 'Trailblazer::Operation' do
-      TBTenSteps.call(a: 1, b: 2)
-    end
-  end
+  b.report 'Trailblazer::Operation' do
+    TBTenSteps.call(a: 1, b: 2)
+  end if with_trailblazer
 
-  if ENV['WITH_PORO']
-    b.report 'PORO' do
-      POROTenSteps.call
-    end
-  end
+  b.report 'PORO' do
+    POROTenSteps.call
+  end if with_poro
 
   b.compare!
-end unless ENV['SKIP_10']
+end
 puts

data/bin/examples.rb

@@ -19,6 +19,16 @@ class FlowsSummator
   end
 end
 
+class FlowsRailwaySummator
+  include Flows::Railway
+
+  step :sum
+
+  def sum(a:, b:)
+    ok(sum: a + b)
+  end
+end
+
 class POROSummator
   def self.call(a:, b:)
     a + b
@@ -46,7 +56,7 @@ class TBSummator < Trailblazer::Operation
 end
 
 #
-# Task: 10 steps which returs simple value
+# Task: 10 steps which returns simple value
 #
 
 class FlowsTenSteps
@@ -78,6 +88,32 @@ class FlowsTenSteps
   def s10(**); ok(data: :ok); end
 end
 
+class FlowsRailwayTenSteps
+  include Flows::Railway
+
+  step :s1
+  step :s2
+  step :s3
+  step :s4
+  step :s5
+  step :s6
+  step :s7
+  step :s8
+  step :s9
+  step :s10
+
+  def s1(**); ok(s1: true); end
+  def s2(s1:); ok(s2: s1); end
+  def s3(s2:); ok(s3: s2); end
+  def s4(s3:); ok(s4: s3); end
+  def s5(s4:); ok(s5: s4); end
+  def s6(s5:); ok(s6: s5); end
+  def s7(s6:); ok(s7: s6); end
+  def s8(s7:); ok(s8: s7); end
+  def s9(s8:); ok(s9: s8); end
+  def s10(s9:); ok(data: :ok); end
+end
+
 class POROTenSteps
   class << self
     def call()

data/bin/profile_10steps

@@ -9,6 +9,7 @@ require 'stackprof'
 require_relative './examples'
 
 flows_ten_steps = FlowsTenSteps.new
+flows_railway_ten_steps = FlowsRailwayTenSteps.new
 
 build_output_name = '10steps_build_10k_times'
 exec_output_name = '10steps_execution_10k_times'
@@ -18,47 +19,88 @@ exec_output_name = '10steps_execution_10k_times'
 #
 RubyProf.measure_mode = RubyProf::WALL_TIME
 
+
 puts 'Build with RubyProf...'
+
 result = RubyProf.profile do
   10_000.times do
     FlowsTenSteps.new
   end
 end
 printer = RubyProf::MultiPrinter.new(result)
-printer.print(path: 'profile', profile: build_output_name)
+printer.print(path: 'profile', profile: "#{build_output_name}_operaion")
+
+result = RubyProf.profile do
+  10_000.times do
+    FlowsRailwayTenSteps.new
+  end
+end
+printer = RubyProf::MultiPrinter.new(result)
+printer.print(path: 'profile', profile: "#{build_output_name}_railway")
+
 
 puts 'Execution with RubyProf...'
+
 result = RubyProf.profile do
   10_000.times {
     flows_ten_steps.call
   }
 end
 printer = RubyProf::MultiPrinter.new(result)
-printer.print(path: 'profile', profile: exec_output_name)
+printer.print(path: 'profile', profile: "#{exec_output_name}_operation")
+
+result = RubyProf.profile do
+  10_000.times {
+    flows_railway_ten_steps.call
+  }
+end
+printer = RubyProf::MultiPrinter.new(result)
+printer.print(path: 'profile', profile: "#{exec_output_name}_railway")
+
 
 #
 # StackProf
 #
 
 puts 'Build with StackProf...'
+
 result = StackProf.run(mode: :wall, raw: true) do
   10_000.times do
     FlowsTenSteps.new
   end
 end
-File.write("profile/#{build_output_name}.json", JSON.generate(result))
+File.write("profile/#{build_output_name}_operation.json", JSON.generate(result))
+
+result = StackProf.run(mode: :wall, raw: true) do
+  10_000.times do
+    FlowsRailwayTenSteps.new
+  end
+end
+File.write("profile/#{build_output_name}_railway.json", JSON.generate(result))
+
 
 puts 'Execution with StackProf...'
+
 result = StackProf.run(mode: :wall, raw: true) do
   10_000.times do
     flows_ten_steps.call
   end
 end
-File.write("profile/#{exec_output_name}.json", JSON.generate(result))
+File.write("profile/#{exec_output_name}_operation.json", JSON.generate(result))
+
+result = StackProf.run(mode: :wall, raw: true) do
+  10_000.times do
+    flows_railway_ten_steps.call
+  end
+end
+File.write("profile/#{exec_output_name}_railway.json", JSON.generate(result))
+
 
 puts
 puts 'Install speedscope:'
 puts '  npm i -g speedscope'
 puts
-puts "speedscope profile/#{build_output_name}.json"
-puts "speedscope profile/#{exec_output_name}.json"
+puts "speedscope profile/#{build_output_name}_operation.json"
+puts "speedscope profile/#{build_output_name}_railway.json"
+puts "speedscope profile/#{exec_output_name}_operation.json"
+puts "speedscope profile/#{exec_output_name}_railway.json"

data/docs/CNAME

@@ -0,0 +1 @@
+flows.ffloyd.tech

data/docs/README.md

@@ -0,0 +1,197 @@
+# Flows
+
+[![Build Status](https://github.com/ffloyd/flows/workflows/Build/badge.svg)](https://github.com/ffloyd/flows/actions)
+[![codecov](https://codecov.io/gh/ffloyd/flows/branch/master/graph/badge.svg)](https://codecov.io/gh/ffloyd/flows)
+[![Gem Version](https://badge.fury.io/rb/flows.svg)](https://badge.fury.io/rb/flows)
+
+Small and fast ruby framework for implementing railway-like operations.
+By design it is close to [Trailblazer::Operation](http://trailblazer.to/gems/operation/2.0/) and [Dry::Transaction](https://dry-rb.org/gems/dry-transaction/),
+but has simpler and flexible DSLs for defining operations and matching results. Also `flows` is faster, see [Performance](overview/performance.md).
+
+`flows` has no production dependencies so it can be used with any framework and cannot bring dependency incompatibilities.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'flows'
+```
+
+And then execute:
+
+```sh
+bundle
+```
+
+Or install it yourself as:
+
+```sh
+gem install flows
+```
+
+## Flows::Result
+
+Wrap your data into Result Objects and use convenient matchers for making decisions:
+
+```ruby
+class Example
+  include Flows::Result::Helpers
+
+  def divide(a, b)
+    return err(:zero_division, msg: 'Division by zero is forbidden') if b.zero?
+
+    result = a / b
+
+    if result.negative?
+      ok(:negative, div: result)
+    else
+      ok(:positive, div: result)
+    end
+  end
+
+  def dispatch(result)
+    case result
+    when match_ok(:positive)
+      puts 'Positive result: ' + result.unwrap[:div]
+    when match_ok(:negative)
+      puts 'Negative result: ' + result.unwrap[:div]
+    when match_err
+      raise result.error[:msg]
+    end
+  end
+end
+
+example = Example.new
+
+result = example.divide(4, 2)
+
+example.dispatch(result) # => Positive result: 2
+```
+
+Features:
+
+* different classes for successful and failure results (`Flows::Result::Ok` and `Flows::Result::Err`)
+* each result has status (`:positive`, `:negative` and `:zero_division` in the provided example are result statuses)
+* convenient helpers for creating and matching Result Objects (`#ok`, `#err`, `#math_ok`, `#match_err`)
+* different data accessor for successful (`#unwrap`) and failure (`#error`) results (prevents using failure objects as successful ones)
+* Do Notation (like [this one](https://dry-rb.org/gems/dry-monads/1.0/do-notation/) but with a bit [different API](result_objects/do_notation.md))
+* result has metadata - this may be used for storing execution metadata (execution time, for example, or something for good error reporting)
+
+More details in a [Result Object Basic Usage Guide](result_objects/basic_usage.md).
+
+## Flows::Railway
+
+Organize subsequent data transformations (result of a step becomes input for a next step or a final result):
+
+```ruby
+class ExampleRailway
+  include Flows::Railway
+
+  step :validate
+  step :add_10
+  step :mul_2
+
+  def validate(x:)
+    return err(:invalid_type, msg: 'Invalid argument type') unless x.is_a?(Numeric)
+
+    ok(x: x)
+  end
+
+  def add_10(x:)
+    ok(x: x + 10)
+  end
+
+  def mul_2(x:)
+    ok(x: x * 2)
+  end
+end
+
+example = ExampleRailway.new
+
+example.call(x: 2)
+# => Flows::Result::Ok with data `{x: 24}`
+
+example.call(x: 'invalid')
+# => Flows::Result::Err with status `:invalid_type` and data `msg: 'Invalid argument type'`
+# methods `#add_10` and `#mul_2` not even executed
+# because Railway stops execution on a first failure result
+```
+
+Features:
+
+* Good composition: `Railway` returns Result Object, step returns Result Object - so you may easily extract steps into separate `Railway`, etc.
+* Support for inheritance (child class may redefine steps or append new steps to the end of flow)
+* Less runtime overhead than in `Flows::Operaion`
+* Override steps implementations using dependency injection on initialization (`.new(deps: {...})`)
+
+More details in a [Railway Basic Usage Guide](railway/basic_usage.md).
+
+## Flows::Operation
+
+If you can draw your business logic in BPMN - you can code it using Operations:
+
+```ruby
+class ExampleOperation
+  include Flows::Operation
+
+  step :fetch_facebook_profile, routes(when_err => :handle_fetch_error)
+  step :fetch_twitter_profile, routes(when_err => :handle_fetch_error)
+  step :extract_person_data
+
+  track :handle_fetch_error do
+    step :track_fetch_error
+    step :make_fetch_error
+  end
+
+  ok_shape :person
+  err_shape :message
+
+  def fetch_facebook_profile(email:, **)
+    result = some_fb_fetcher(email)
+    return err unless result
+
+    ok(facebook_data: result)
+  end
+
+  def fetch_twitter_profile(email:, **)
+    result = some_twitter_fetcher(email)
+    return err unless result
+
+    ok(twitter_data: result)
+  end
+
+  def extract_person_data(facebook_data:, twitter_data:, **)
+    ok(person: facebook_data.merge(twitter_data))
+  end
+
+  def track_fetch_error(**)
+    # send event to New Relic, etc.
+    ok
+  end
+
+  def make_fetch_error(**)
+    err(:fetch_error, message: 'Fetch error')
+  end
+end
+
+operation = ExampleOperation.new
+
+operation.call(email: 'whatever@email.com')
+```
+
+Features:
+
+* Superset of `Railway` - any Railway can be converted into Operation in a seconds
+* Result Shaping - return only data you need
+* Branching and Tracks - you may do even loops if you brave enough
+* Good Composition - because everything here returns Result Objects and receives keyword arguments (or hash) you may compose Operations and Railways without any additional effort. Generally speaking - Railway is a simplified operation.
+
+More details in a [Operation Basic Usage Guide](operation/basic_usage.md).
+
+## Flows::Flow
+
+Railway and Operation use `Flows::Flow` under the hood to transform your step definitions into executable workflow.
+It's not recommended to use Flow in your business code but it's a good tool for building your own abstractions in yours libraries.
+
+More details [here](flow/general_idea.md).