flows 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12213313efb3ea2ba0d786043d82ac3ec4279547de96f3b136303eab4078acf9
-  data.tar.gz: a383ca5ae142ddf2385f0d17e12f4f41f353c4dae577743638b1d2db8748ba05
+  metadata.gz: 3a69e7b183fcc1a9a0e0eabeaac0e66aff9fc55ea458fa34a5c37de86c7970ab
+  data.tar.gz: 20dbb58536ba20c0f7c7032757679ea968088965890851e93af81e2b4cb148f4
 SHA512:
-  metadata.gz: f4ec655af858b58f0ef7da44cbb79d1fc6dfa9d49c985cc5e4fbc504b349a8ca8d68e7b78be73e1b3ec1c7f28f121f7b2456fd7477ef88f5f04aa537bd63c232
-  data.tar.gz: 8cc7a7e6693c47c2463e8bf2dbf1b6ec4492a3c3125dfd97fbbc8a3e9e1af2763ff6e48320c846cd5a72b44d4c49fae84e14a57b2faba8842154b0793e6591f0
+  metadata.gz: b606d7df548e65d694f4700ecf6991667bca8f6626a41111bce6cbe9f8949ad0c5cfc58830fd1596b1fc3c170eaca7aed2b4f8f83092a5a7d174979978ece70b
+  data.tar.gz: 4fbfd1e9422aca8b7800b4930d32a7a3a4f4eca67eceab08cf0b20fcde24ef628d677f5bc40ffa1f7a1c9c3af6f1f80de78a6e248adf145f23f63d3d4ae6c77c

data/.gitignore

@@ -9,3 +9,7 @@
 
 # rspec failure tracking
 .rspec_status
+
+# profile results folder
+/profile/
+!/profile/.keep

data/Gemfile.lock

@@ -1,19 +1,45 @@
 PATH
   remote: .
   specs:
-    flows (0.0.2)
+    flows (0.1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.0)
+    benchmark-ips (2.7.2)
     codecov (0.1.14)
       json
       simplecov
       url
     coderay (1.1.2)
+    concurrent-ruby (1.1.5)
     diff-lcs (1.3)
     docile (1.3.1)
+    dry-configurable (0.8.3)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 0.4, >= 0.4.7)
+    dry-container (0.7.2)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 0.1, >= 0.1.3)
+    dry-core (0.4.9)
+      concurrent-ruby (~> 1.0)
+    dry-equalizer (0.2.2)
+    dry-events (0.2.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 0.4)
+      dry-equalizer (~> 0.2)
+    dry-matcher (0.8.1)
+      dry-core (>= 0.4.7)
+    dry-monads (1.3.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 0.4, >= 0.4.4)
+      dry-equalizer
+    dry-transaction (0.13.0)
+      dry-container (>= 0.2.8)
+      dry-events (>= 0.1.0)
+      dry-matcher (>= 0.7.0)
+      dry-monads (>= 0.4.0)
     jaro_winkler (1.5.2)
     json (2.2.0)
     method_source (0.9.2)
@@ -51,12 +77,21 @@ GEM
       rubocop (>= 0.58.0)
     rubocop-rspec (1.32.0)
       rubocop (>= 0.60.0)
+    ruby-prof (1.0.0)
     ruby-progressbar (1.10.0)
     simplecov (0.16.1)
       docile (~> 1.1)
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
+    stackprof (0.2.12)
+    trailblazer-activity (0.8.4)
+      trailblazer-context (>= 0.1.4)
+    trailblazer-activity-dsl-linear (0.1.8)
+      trailblazer-activity (>= 0.8.3, < 1.0.0)
+    trailblazer-context (0.1.4)
+    trailblazer-operation (0.5.2)
+      trailblazer-activity-dsl-linear (>= 0.1.6, < 1.0.0)
     unicode-display_width (1.5.0)
     url (0.3.2)
 
@@ -64,8 +99,10 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  benchmark-ips
   bundler (~> 2.0)
   codecov
+  dry-transaction
   flows!
   pry
   rake (~> 10.0)
@@ -73,7 +110,10 @@ DEPENDENCIES
   rubocop
   rubocop-performance
   rubocop-rspec
+  ruby-prof
   simplecov
+  stackprof
+  trailblazer-operation
 
 BUNDLED WITH
    2.0.1

data/README.md

@@ -4,7 +4,11 @@
 [![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)
 
-_TODO_
+Small and fast ruby framework for implementing railway-like operations.
+By design it close to [Trailblazer::Operation](http://trailblazer.to/gems/operation/2.0/) and [Dry::Transaction](https://dry-rb.org/gems/dry-transaction/),
+but has more simpler and flexible DSL for defining operations and matching results. Also `flows` is significantly faster.
+
+`flows` has no production dependencies so you can use it with any framework.
 
 ## Installation
 
@@ -24,7 +28,297 @@ Or install it yourself as:
 
 ## Usage
 
-_TODO_
+### `Flows::Flow`
+
+Low-level instrument for defining execution flows. Used internally as execution engine for `Flows::Operation`.
+Check out source code and specs for details.
+
+### `Flows::Result`
+
+Result Object implementation. Inspired by [Dry::Monads::Result](https://dry-rb.org/gems/dry-monads/1.0/result/) and
+[Rust Result Objects](https://doc.rust-lang.org/1.30.0/book/2018-edition/ch09-02-recoverable-errors-with-result.html).
+
+Main concepts & conventions:
+
+* separate classes for successful (`Flows::Result::Ok`) and failure (`Flows::Result::Err`) results
+  * both classes has same parent class `Flows::Result`
+* result data should be a `Hash` with symbol keys and any values
+* result has a status
+  * default status for successful results is `:success`
+  * default status for failure results is `:failure`
+
+Basic usage:
+
+```ruby
+# create successful result with data {a: 1, b: 2}
+result_ok = Flows::Result::Ok.new(a:1, b: 2)
+
+# get `:a` from result
+result_ok.unwrap[:a] # 1
+
+# get error data from result
+result_ok.error[:a] # raises exception
+
+# get status from result
+result_ok.status # :success
+
+# boolean flags
+result_ok.ok? # true
+result_ok.err? # false
+
+# create successful result with data {a: 1, b: 2} and status `:custom`
+result_ok_custom = Flows::Result::Ok.new({ a: 1, b: 2 }, status: :custom)
+
+# get status from result
+result_ok_custom.status # :custom
+
+# create failure result with data {a: 1, b: 2}
+result_err = Flows::Result::Err.new(a:1, b: 2)
+
+# get `:a` from result
+result_err.unwrap[:a] # raises exception
+
+# get error data from result
+result_err.error[:a] # 1
+
+# get status from result
+result_err.status # :failure
+
+# boolean flags
+result_ok.ok? # false
+result_ok.err? # true
+
+# create failure result with data {a: 1, b: 2} and status `:custom`
+result_err_custom = Flows::Result::Err.new({ a: 1, b: 2 }, status: :custom)
+
+# get status from result
+result_err_custom.status # :custom
+```
+
+Mixin `Flows::Result::Helpers` contains tools for simpler generating and matching Result Objects:
+
+```ruby
+include Flows::Result::Helpers
+
+# create successful result with data {a: 1, b: 2}
+result_ok = ok(a:1, b: 2)
+
+# create successful result with data {a: 1, b: 2} and status `:custom`
+result_ok_custom = ok(:custom, a: 1, b: 2)
+
+# create failure result with data {a: 1, b: 2}
+result_err = err(a:1, b: 2)
+
+# create failure result with data {a: 1, b: 2} and status `:custom`
+result_err_custom = err(:custom, a: 1, b: 2)
+
+# matching helpers
+result = ...
+
+case result
+when match_ok(:custom)
+  # matches only successful results with status :custom
+when match_ok
+  # matches only successful results with any status
+when match_err(:custom)
+  # matches only failure results with status :custom
+when match_err
+  # matches only failure results with any status
+end
+```
+
+### `Flows::Operation`
+
+Let's solve simple task using operation:
+
+* given numbers `a` and `b`
+* result should contain sum of this numbers
+* result should contain square of this sum
+
+```ruby
+class Summator
+  # Make this class an operation by including this module.
+  # It adds DSL, initializer and call method.
+  # Also it includes Flows::Result::Helper both on DSL and instance level.
+  include Flows::Operation
+  
+  # This is step definitions.
+  # In simplest form step defined by its name and
+  # step implementation expected to be in a method
+  # with same name.
+  #
+  # Steps will be executed in a definition order.
+  step :validate
+  step :calc_sum
+  step :calc_square
+  
+  # Which keys of operation data we want to expose on success
+  ok_shape :sum, :sum_square
+  
+  # Which keys of operation data we want to expose on failure 
+  err_shape :message
+  
+  # Step implementation receives execution context as keyword arguments.
+  # For the first step context equals to operation arguments.
+  #
+  # Step implementation must return Result Object.
+  # Result Objects's data will be merged into operation context.
+  # 
+  # If result is successful - next step will be executed.
+  # If not - operation terminates and returns failure.
+  def validate(a:, b:, **)
+    err(message: 'a is not a number') if !a.is_a?(Number)
+    err(message: 'b is not a number') if !b.is_a?(Number)
+    
+    ok
+  end
+  
+  def calc_sum(a:, b:, **)
+    ok(sum: a + b)
+  end
+  
+  # We may get data from previous steps because all results' data are merged to context.
+  def calc_square(sum:, **)
+    ok(sum_square: a * b)
+  end
+end
+
+
+# prepare operation
+operation = Summator.new
+
+# execute operation
+result = operation.call(a: 1, b: 2)
+
+result.ok? # true
+result.unwrap # { sum: 3, sum_square: 9 } - only keys from success shape present
+
+
+result = operation.call(a: nil, b: nil)
+
+result.ok? # false
+result.error # { message: 'a is not a number' } - only keys from error shape present
+```
+
+#### Result Shapes
+
+You may limit list of exposed fields by defining success and failure shapes. _After_ step definitions use `ok_shape` to define shapes of success result,
+and `err_shape` to define shapes of failure result. Examples:
+
+```ruby
+# Set exposed keys for :success status of successful result.
+#
+# Success result will have shape like { key1: ..., key2: ... }
+#
+# If one of keys is missing in the final operation context an exception will be raised.
+ok_shape :key1, :key2
+
+# Set different exposed keys for different statuses.
+#
+# Operation result status is a status of last executed step result.
+ok_shape status1: [:key1, :key2],
+        status2: [:key3]
+        
+# Failure shapes defined in the same way:
+err_shape :key1, :key2
+err_shape status1: [:key1, :key2],
+        status2: [:key3]
+```
+
+Operation definition should have exact one `ok_shape` DSL-call and zero or one `err_shape` DSL-call. If you want to disable shaping
+you can write `no_shape` DSL-call instead of shape definitions.
+
+#### Routing & Tracks
+
+You define side tracks, even nested ones:
+
+```ruby
+step :outer_1 # next step is outer_2
+
+track :some_track do
+  step :inner_1 # next step is inner_2
+  track :inner_track do
+    step :deep_1 # next step is deep_2
+    step :deep_2 # next step is inner_2
+  end
+  step :inner_2 # next step in outer_2
+end
+
+step :outer_2
+```
+
+In definition above tracks will not be used because there is no routes to this tracks. You may define routing like this: 
+
+```ruby
+# if result is successful and has status :to_some_track - next step will be inner_1 
+# for any other successful results - outer_2
+step :outer_1,
+  match_ok(:to_some_track) => :some_track
+
+track :some_track do
+  step :inner_1, match_err => :inner_track # redirect to inner_track on failure result
+  track :inner_track do
+    step :deep_1, match_ok(:some_status) => :outer_2 # you may redirect to steps too
+    step :deep_2
+  end
+  step :inner_2
+end
+
+step :outer_2
+```
+
+#### Lambda Steps
+
+You can use lambda for in-place step implementation:
+
+```ruby
+step :name, ->(a:, b:, **) { ok(sum: a + b) }
+```
+
+#### Dependency Injection
+
+You can override or inject step implementation on initialization:
+
+```ruby
+class Summator
+  include Flows::Operation
+  
+  step :sum
+  
+  ok_shape :sum
+end
+
+summator = Summator.new(deps: {
+  sum: ->(a:, b:, **) { ok(sum: a + b) }
+})
+
+summator.call(a: 1, b: 2).unwrap[:sum] # 3
+```
+
+#### Wrapping steps
+
+You can wrap several steps with some logic:
+
+```ruby
+step :first
+
+wrap :wrapper do
+  step :wrapped
+end
+
+def wrapper(**context)
+  # do smth
+  result = yield # execute wrapped steps
+  # do smth or modify result
+  result
+end
+```
+
+There is routing limitation when you use wrap:
+
+* outside `wrap` block you may route to wrapped block by wrapper name (`:wrapper` in the provided example)
+* you may route wrapped steps only to wrapped steps in the same wrap block
+* you cannot route to wrapped steps from outside
 
 ## Development
 

data/bin/benchmark

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby
+# rubocop:disable all
+
+require 'bundler/setup'
+require 'benchmark/ips'
+
+require_relative './examples'
+
+puts '-' * 50
+puts '- task: A + B, one step implementation'
+puts '-' * 50
+
+flows_summator = FlowsSummator.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::Operation (build once)' do
+    flows_summator.call(a: 1, b: 2)
+  end
+
+  unless ENV['FLOWS_ONLY']
+    b.report 'Dry::Transaction (build each time)' do
+      DrySummator.new.call(a: 1, b: 2)
+    end
+
+    b.report 'Dry::Transaction (build once)' do
+      dry_summator.call(a: 1, b: 2)
+    end
+
+    b.report 'Trailblazer::Operation' do
+      TBSummator.call(a: 1, b: 2)
+    end
+  end
+
+  if ENV['WITH_PORO']
+    b.report 'PORO' do
+      POROSummator.call(a: 1, b: 2)
+    end
+  end
+
+  b.compare!
+end unless ENV['SKIP_SUM']
+puts
+
+
+puts '-' * 50
+puts '- task: ten steps returns successful result'
+puts '-' * 50
+
+flows_ten_steps = FlowsTenSteps.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::Operation (build once)' do
+    flows_ten_steps.call(a: 1, b: 2)
+  end
+
+  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
+
+    b.report 'Trailblazer::Operation' do
+      TBTenSteps.call(a: 1, b: 2)
+    end
+  end
+
+  if ENV['WITH_PORO']
+    b.report 'PORO' do
+      POROTenSteps.call
+    end
+  end
+
+  b.compare!
+end unless ENV['SKIP_10']
+puts

data/bin/demo

@@ -27,8 +27,8 @@ class DivisionOperation
   step :check_for_zero
   step :divide
 
-  success :result
-  failure :error
+  ok_shape :result
+  err_shape :error
 
   def check_for_zero(denominator:, **)
     if denominator.zero?
@@ -49,8 +49,8 @@ class NestedDivisionOperation
 
   step :do_division
 
-  success :result
-  failure :error
+  ok_shape :result
+  err_shape :error
 
   def do_division(**params)
     DivisionOperation.new.call(**params)

data/bin/examples.rb

@@ -0,0 +1,159 @@
+# rubocop:disable all
+require 'flows'
+require 'dry/transaction'
+require 'trailblazer/operation'
+
+#
+# Task: a + b = ?
+#
+
+class FlowsSummator
+  include Flows::Operation
+
+  step :sum
+
+  ok_shape :sum
+
+  def sum(a:, b:, **)
+    ok(sum: a + b)
+  end
+end
+
+class POROSummator
+  def self.call(a:, b:)
+    a + b
+  end
+end
+
+class DrySummator
+  include Dry::Transaction
+
+  step :sum
+
+  private
+
+  def sum(a:, b:)
+    Success(a + b)
+  end
+end
+
+class TBSummator < Trailblazer::Operation
+  step :sum
+
+  def sum(opts, a:, b:, **)
+    opts[:sum] = a + b
+  end
+end
+
+#
+# Task: 10 steps which returs simple value
+#
+
+class FlowsTenSteps
+  include Flows::Operation
+
+  step :s1
+  step :s2
+  step :s3
+  step :s4
+  step :s5
+  step :s6
+  step :s7
+  step :s8
+  step :s9
+  step :s10
+
+  ok_shape :data
+
+  def s1(**); ok(s1: true); end
+  def s2(**); ok(s2: true); end
+  def s3(**); ok(s3: true); end
+  def s4(**); ok(s4: true); end
+  def s5(**); ok(s5: true); end
+  def s5(**); ok(s5: true); end
+  def s6(**); ok(s6: true); end
+  def s7(**); ok(s7: true); end
+  def s8(**); ok(s8: true); end
+  def s9(**); ok(s9: true); end
+  def s10(**); ok(data: :ok); end
+end
+
+class POROTenSteps
+  class << self
+    def call()
+      s1
+      s2
+      s3
+      s4
+      s5
+      s6
+      s7
+      s8
+      s9
+      s10
+    end
+
+    def s1; true; end
+    def s2; true; end
+    def s3; true; end
+    def s4; true; end
+    def s5; true; end
+    def s6; true; end
+    def s7; true; end
+    def s8; true; end
+    def s9; true; end
+    def s10; true; end
+  end
+end
+
+class DryTenSteps
+  include Dry::Transaction
+
+  step :s1
+  step :s2
+  step :s3
+  step :s4
+  step :s5
+  step :s6
+  step :s7
+  step :s8
+  step :s9
+  step :s10
+
+  private
+
+  def s1; Success(true); end
+  def s2; Success(true); end
+  def s3; Success(true); end
+  def s4; Success(true); end
+  def s5; Success(true); end
+  def s6; Success(true); end
+  def s7; Success(true); end
+  def s8; Success(true); end
+  def s9; Success(true); end
+  def s10; Success(true); end
+end
+
+class TBTenSteps < Trailblazer::Operation
+  step :s1
+  step :s2
+  step :s3
+  step :s4
+  step :s5
+  step :s6
+  step :s7
+  step :s8
+  step :s9
+  step :s10
+
+  def s1(opts, **); opts[:s1] = true; end
+  def s2(opts, **); opts[:s2] = true; end
+  def s3(opts, **); opts[:s3] = true; end
+  def s4(opts, **); opts[:s4] = true; end
+  def s5(opts, **); opts[:s5] = true; end
+  def s6(opts, **); opts[:s6] = true; end
+  def s7(opts, **); opts[:s7] = true; end
+  def s8(opts, **); opts[:s8] = true; end
+  def s9(opts, **); opts[:s9] = true; end
+  def s10(opts, **); opts[:s10] = true; end
+end