flows 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a69e7b183fcc1a9a0e0eabeaac0e66aff9fc55ea458fa34a5c37de86c7970ab
-  data.tar.gz: 20dbb58536ba20c0f7c7032757679ea968088965890851e93af81e2b4cb148f4
+  metadata.gz: eed3e3ba742be2b25c1ae3ca7b52d2db3418183e0950616409ef8d05232365de
+  data.tar.gz: c2f340f63e6e55178426c28fcfe29aa6d6c9af7d9a4b539d43461f068f4a6082
 SHA512:
-  metadata.gz: b606d7df548e65d694f4700ecf6991667bca8f6626a41111bce6cbe9f8949ad0c5cfc58830fd1596b1fc3c170eaca7aed2b4f8f83092a5a7d174979978ece70b
-  data.tar.gz: 4fbfd1e9422aca8b7800b4930d32a7a3a4f4eca67eceab08cf0b20fcde24ef628d677f5bc40ffa1f7a1c9c3af6f1f80de78a6e248adf145f23f63d3d4ae6c77c
+  metadata.gz: 44a6ac9cdcedb674aab92373647582e038602c9459361d1ccbc6502cd78556835042fb81004c2329f1c1a95108371040dddb829fbd11a8eaa20bf310817163f3
+  data.tar.gz: 333ff1f85e39a794c5e4073e7deeca887562a0568497cd480d75b26338aff242dc8c5d1a8f67ce822083e894beecfe033b7abcffe25e931490de53db7e52cf29

data/.github/workflows/build.yml

@@ -0,0 +1,43 @@
+name: Build
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+  schedule:
+    - cron: 0 2 * * 1-5
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - 2.5.x
+          - 2.6.x
+    steps:
+      - uses: actions/checkout@v1
+      - name: Set up Ruby
+        uses: actions/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install Bundler
+        run: gem install bundler
+      - name: Install Hunspell
+        run: sudo apt-get install hunspell
+      - name: Install Deps
+        run: bundle install --jobs 4 --retry 3
+      - name: Rubocop
+        run: bundle exec rubocop
+      - name: RSpec
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+        run: bundle exec rspec
+      - name: Markdown Linter (docs)
+        run: bundle exec mdl docs/**/*.md README.md
+      - name: Spelling Check (docs & code)
+        run: bundle exec forspell

data/.mdlrc

@@ -0,0 +1 @@
+rules "~MD013", "~MD033"

data/.rubocop.yml

@@ -1,6 +1,7 @@
 require:
   - rubocop-rspec
   - rubocop-performance
+  - rubocop-md
 
 AllCops:
   TargetRubyVersion: 2.6
@@ -20,3 +21,27 @@ Metrics/ParameterLists:
 
 Style/WhileUntilModifier:
   Enabled: false
+
+Naming/UncommunicativeMethodParamName:
+  Exclude:
+    - '**/*.md'
+
+Style/MixinUsage:
+  Exclude:
+    - '**/*.md'
+
+Lint/UnusedMethodArgument:
+  Exclude:
+    - '**/*.md'
+
+Lint/UnusedBlockArgument:
+  Exclude:
+    - '**/*.md'
+
+Lint/UnreachableCode:
+  Exclude:
+    - 'docs/result_objects/do_notation.md'
+
+Lint/Void:
+  Exclude:
+    - 'docs/result_objects/do_notation.md'

data/Gemfile

@@ -2,3 +2,9 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in flows.gemspec
 gemspec
+
+# temporary dev dependencies,
+# move it to gemspec after PRs will be merged into realesed version of a gem
+group :development do
+  gem 'mdl', github: 'ffloyd/markdownlint', branch: 'update-kramdown-dep'
+end

data/Gemfile.lock

@@ -1,12 +1,24 @@
+GIT
+  remote: git://github.com/ffloyd/markdownlint.git
+  revision: 801cb12f645d894e0d262bb4908d8086b6dd23bc
+  branch: update-kramdown-dep
+  specs:
+    mdl (0.5.0)
+      kramdown (~> 2.0)
+      kramdown-parser-gfm (~> 1.0)
+      mixlib-cli (~> 1.7, >= 1.7.0)
+      mixlib-config (~> 2.2, >= 2.2.1)
+
 PATH
   remote: .
   specs:
-    flows (0.1.0)
+    flows (0.2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.0)
+    backports (3.15.0)
     benchmark-ips (2.7.2)
     codecov (0.1.14)
       json
@@ -14,8 +26,9 @@ GEM
       url
     coderay (1.1.2)
     concurrent-ruby (1.1.5)
+    crass (1.0.4)
     diff-lcs (1.3)
-    docile (1.3.1)
+    docile (1.3.2)
     dry-configurable (0.8.3)
       concurrent-ruby (~> 1.0)
       dry-core (~> 0.4, >= 0.4.7)
@@ -29,9 +42,9 @@ GEM
       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)
+    dry-matcher (0.8.2)
+      dry-core (>= 0.4.8)
+    dry-monads (1.3.1)
       concurrent-ruby (~> 1.0)
       dry-core (~> 0.4, >= 0.4.4)
       dry-equalizer
@@ -40,60 +53,99 @@ GEM
       dry-events (>= 0.1.0)
       dry-matcher (>= 0.7.0)
       dry-monads (>= 0.4.0)
-    jaro_winkler (1.5.2)
+    equatable (0.6.1)
+    ffi (1.11.1)
+    ffi-hunspell (0.4.0)
+      ffi (~> 1.0)
+    forspell (0.0.8)
+      backports (~> 3.0)
+      ffi-hunspell
+      highline
+      kramdown (~> 2.0)
+      kramdown-parser-gfm (~> 1.0)
+      parser
+      pastel
+      ruby-progressbar
+      sanitize (~> 5.0)
+      slop (~> 4.6)
+      yard
+    highline (2.0.2)
+    jaro_winkler (1.5.3)
     json (2.2.0)
+    kramdown (2.1.0)
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
     method_source (0.9.2)
+    mini_portile2 (2.4.0)
+    mixlib-cli (1.7.0)
+    mixlib-config (2.2.18)
+      tomlrb
+    nokogiri (1.10.4)
+      mini_portile2 (~> 2.4.0)
+    nokogumbo (2.0.1)
+      nokogiri (~> 1.8, >= 1.8.4)
     parallel (1.17.0)
-    parser (2.6.2.0)
+    parser (2.6.4.1)
       ast (~> 2.4.0)
+    pastel (0.7.3)
+      equatable (~> 0.6)
+      tty-color (~> 0.5)
     pry (0.12.2)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
-    psych (3.1.0)
     rainbow (3.0.0)
     rake (10.5.0)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
       rspec-expectations (~> 3.8.0)
       rspec-mocks (~> 3.8.0)
-    rspec-core (3.8.0)
+    rspec-core (3.8.2)
       rspec-support (~> 3.8.0)
-    rspec-expectations (3.8.2)
+    rspec-expectations (3.8.4)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
-    rspec-mocks (3.8.0)
+    rspec-mocks (3.8.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
-    rspec-support (3.8.0)
-    rubocop (0.67.1)
+    rspec-support (3.8.2)
+    rubocop (0.74.0)
       jaro_winkler (~> 1.5.1)
       parallel (~> 1.10)
-      parser (>= 2.5, != 2.5.1.1)
-      psych (>= 3.1.0)
+      parser (>= 2.6)
       rainbow (>= 2.2.2, < 4.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 1.6)
-    rubocop-performance (1.0.0)
-      rubocop (>= 0.58.0)
-    rubocop-rspec (1.32.0)
+      unicode-display_width (>= 1.4.0, < 1.7)
+    rubocop-md (0.3.0)
+      rubocop (~> 0.60)
+    rubocop-performance (1.4.1)
+      rubocop (>= 0.71.0)
+    rubocop-rspec (1.35.0)
       rubocop (>= 0.60.0)
     ruby-prof (1.0.0)
-    ruby-progressbar (1.10.0)
-    simplecov (0.16.1)
+    ruby-progressbar (1.10.1)
+    sanitize (5.1.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.8.0)
+      nokogumbo (~> 2.0)
+    simplecov (0.17.1)
       docile (~> 1.1)
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
+    slop (4.7.0)
     stackprof (0.2.12)
-    trailblazer-activity (0.8.4)
+    tomlrb (1.2.8)
+    trailblazer-activity (0.9.0)
       trailblazer-context (>= 0.1.4)
-    trailblazer-activity-dsl-linear (0.1.8)
-      trailblazer-activity (>= 0.8.3, < 1.0.0)
+    trailblazer-activity-dsl-linear (0.2.0)
+      trailblazer-activity (>= 0.9.0, < 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)
+    tty-color (0.5.0)
+    unicode-display_width (1.6.0)
     url (0.3.2)
+    yard (0.9.20)
 
 PLATFORMS
   ruby
@@ -104,10 +156,13 @@ DEPENDENCIES
   codecov
   dry-transaction
   flows!
+  forspell (~> 0.0.8)
+  mdl!
   pry
   rake (~> 10.0)
   rspec (~> 3.0)
   rubocop
+  rubocop-md
   rubocop-performance
   rubocop-rspec
   ruby-prof

data/README.md

@@ -1,14 +1,14 @@
 # Flows
 
-[![Build Status](https://travis-ci.com/ffloyd/flows.svg?branch=master)](https://travis-ci.com/ffloyd/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 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.
+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 DSL for defining operations and matching results. Also `flows` is faster, see [Performance](#performance).
 
-`flows` has no production dependencies so you can use it with any framework.
+`flows` has no production dependencies so it can be used with any framework.
 
 ## Installation
 
@@ -20,11 +20,15 @@ gem 'flows'
 
 And then execute:
 
-    $ bundle
+```sh
+bundle
+```
 
 Or install it yourself as:
 
-    $ gem install flows
+```sh
+gem install flows
+```
 
 ## Usage
 
@@ -51,7 +55,7 @@ Basic usage:
 
 ```ruby
 # create successful result with data {a: 1, b: 2}
-result_ok = Flows::Result::Ok.new(a:1, b: 2)
+result_ok = Flows::Result::Ok.new(a: 1, b: 2)
 
 # get `:a` from result
 result_ok.unwrap[:a] # 1
@@ -73,7 +77,7 @@ result_ok_custom = Flows::Result::Ok.new({ a: 1, b: 2 }, status: :custom)
 result_ok_custom.status # :custom
 
 # create failure result with data {a: 1, b: 2}
-result_err = Flows::Result::Err.new(a:1, b: 2)
+result_err = Flows::Result::Err.new(a: 1, b: 2)
 
 # get `:a` from result
 result_err.unwrap[:a] # raises exception
@@ -101,29 +105,33 @@ Mixin `Flows::Result::Helpers` contains tools for simpler generating and matchin
 include Flows::Result::Helpers
 
 # create successful result with data {a: 1, b: 2}
-result_ok = ok(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)
+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 = ...
+result = SomeOperation.new.call
 
 case result
 when match_ok(:custom)
   # matches only successful results with status :custom
+  do_something
 when match_ok
   # matches only successful results with any status
+  do_something
 when match_err(:custom)
   # matches only failure results with status :custom
+  do_something
 when match_err
   # matches only failure results with any status
+  do_something
 end
 ```
 
@@ -141,7 +149,7 @@ class Summator
   # 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
@@ -151,39 +159,38 @@ class Summator
   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 
+
+  # 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)
-    
+    err(message: 'a is not a number') unless a.is_a?(Number)
+    err(message: 'b is not a number') unless 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)
+    ok(sum_square: sum * sum)
   end
 end
 
-
 # prepare operation
 operation = Summator.new
 
@@ -193,7 +200,6 @@ 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
@@ -202,8 +208,7 @@ result.error # { message: 'a is not a number' } - only keys from error shape pre
 
 #### 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:
+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.
@@ -216,13 +221,13 @@ 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]
-        
+ok_shape status1: %i[key1 key2],
+         status2: [:key3]
+
 # Failure shapes defined in the same way:
 err_shape :key1, :key2
-err_shape status1: [:key1, :key2],
-        status2: [:key3]
+err_shape status1: %i[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
@@ -247,18 +252,19 @@ 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: 
+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 
+# 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
+step :outer_1, routes(
+  when_ok(:to_some_track) => :some_track
+)
 
 track :some_track do
-  step :inner_1, match_err => :inner_track # redirect to inner_track on failure result
+  step :inner * 1, routes(when_err => :inner_track) # redirect to inner_track on any failure result
   track :inner_track do
-    step :deep_1, match_ok(:some_status) => :outer_2 # you may redirect to steps too
+    step :deep_1, routes(when_ok(:some_status) => :outer_2) # you may redirect to steps too
     step :deep_2
   end
   step :inner_2
@@ -267,6 +273,25 @@ end
 step :outer_2
 ```
 
+You also can use less verbose, but shorter form of definition:
+
+```ruby
+step :name,
+     match_ok(:status) => :track_name,
+     match_ok => :track_name
+```
+
+Step has default routes:
+
+```ruby
+routes(
+  when_ok => next_step_name,
+  when_err => :term
+)
+```
+
+Custom routes have bigger priority than default ones. Moreover, default routes can be overriden.
+
 #### Lambda Steps
 
 You can use lambda for in-place step implementation:
@@ -282,15 +307,15 @@ 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) }
-})
+                          sum: ->(a:, b:, **) { ok(sum: a + b) }
+                        })
 
 summator.call(a: 1, b: 2).unwrap[:sum] # 3
 ```
@@ -306,7 +331,7 @@ wrap :wrapper do
   step :wrapped
 end
 
-def wrapper(**context)
+def wrapper(**_context)
   # do smth
   result = yield # execute wrapped steps
   # do smth or modify result
@@ -320,6 +345,107 @@ There is routing limitation when you use wrap:
 * you may route wrapped steps only to wrapped steps in the same wrap block
 * you cannot route to wrapped steps from outside
 
+## Performance
+
+You can compare performance for some cases by executing `bin/benchmark`. Examples for benchmark are presented in `bin/examples.rb`.
+
+`Flows::Operation` and `Dry::Trancation` may be executed in two ways:
+
+_Build once:_ when we create operation instance once (build operation):
+
+```ruby
+operation = OperationClass.new
+
+10_000.times { operation.call }
+```
+
+_Build each time:_ when we create operation instance each execution:
+
+```ruby
+10_000.times { OperationClass.new.call }
+```
+
+`flows` and `dry` are much faster in _build once_ way of using. Note that Trailblazer gives you only one way to execute operation.
+
+### Benchmark Results
+
+Host:
+
+* MacBook Pro (13-inch, 2017, Four Thunderbolt 3 Ports)
+* 3.1 GHz Intel Core i5
+* 8 GB 2133 MHz LPDDR3
+
+Results:
+
+```text
+--------------------------------------------------
+- task: A + B, one step implementation
+--------------------------------------------------
+Warming up --------------------------------------
+Flows::Operation (build each time)
+                         9.147k i/100ms
+Flows::Operation (build once)
+                        25.738k i/100ms
+Dry::Transaction (build each time)
+                         2.294k i/100ms
+Dry::Transaction (build once)
+                        21.836k i/100ms
+Trailblazer::Operation
+                         5.057k i/100ms
+Calculating -------------------------------------
+Flows::Operation (build each time)
+                         96.095k (± 2.3%) i/s -    484.791k in   5.047684s
+Flows::Operation (build once)
+                        281.248k (± 1.7%) i/s -      1.416M in   5.034728s
+Dry::Transaction (build each time)
+                         23.683k (± 1.7%) i/s -    119.288k in   5.038506s
+Dry::Transaction (build once)
+                        237.379k (± 3.3%) i/s -      1.201M in   5.066073s
+Trailblazer::Operation
+                         52.676k (± 1.5%) i/s -    268.021k in   5.089306s
+
+Comparison:
+Flows::Operation (build once):   281248.4 i/s
+Dry::Transaction (build once):   237378.7 i/s - 1.18x  slower
+Flows::Operation (build each time):    96094.9 i/s - 2.93x  slower
+Trailblazer::Operation:    52676.3 i/s - 5.34x  slower
+Dry::Transaction (build each time):    23682.9 i/s - 11.88x  slower
+
+
+--------------------------------------------------
+- task: ten steps returns successful result
+--------------------------------------------------
+Warming up --------------------------------------
+Flows::Operation (build each time)
+                         1.496k i/100ms
+Flows::Operation (build once)
+                         3.847k i/100ms
+Dry::Transaction (build each time)
+                       274.000  i/100ms
+Dry::Transaction (build once)
+                         2.992k i/100ms
+Trailblazer::Operation
+                         1.082k i/100ms
+Calculating -------------------------------------
+Flows::Operation (build each time)
+                         15.013k (± 3.8%) i/s -     76.296k in   5.089734s
+Flows::Operation (build once)
+                         39.239k (± 1.6%) i/s -    196.197k in   5.001538s
+Dry::Transaction (build each time)
+                          2.743k (± 3.7%) i/s -     13.700k in   5.002847s
+Dry::Transaction (build once)
+                         30.441k (± 1.8%) i/s -    152.592k in   5.014565s
+Trailblazer::Operation
+                         11.022k (± 1.4%) i/s -     55.182k in   5.007543s
+
+Comparison:
+Flows::Operation (build once):    39238.6 i/s
+Dry::Transaction (build once):    30440.5 i/s - 1.29x  slower
+Flows::Operation (build each time):    15012.7 i/s - 2.61x  slower
+Trailblazer::Operation:    11022.1 i/s - 3.56x  slower
+Dry::Transaction (build each time):     2743.0 i/s - 14.30x  slower
+```
+
 ## 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.
@@ -328,7 +454,7 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/ffloyd/flows. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at [ffloyd/fflows](https://github.com/ffloyd/flows). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License