flows 0.3.0 → 0.4.0

data/README.md

@@ -5,8 +5,12 @@
 [![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 DSL for defining operations and matching results. Also `flows` is faster, see [Performance](#performance).
+By design it is close to
+[Trailblazer::Operation](http://trailblazer.to/gems/operation/2.0/),
+[Dry::Transaction](https://dry-rb.org/gems/dry-transaction/) and Rust control
+flow style.
+Flows has simple and flexible DSL for defining operations and matching results.
+Also `flows` is faster than Ruby's alternatives.
 
 `flows` has no production dependencies so it can be used with any framework.
 
@@ -15,7 +19,7 @@ but has simpler and flexible DSL for defining operations and matching results. A
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'flows'
+gem 'flows', '~> 0.4'
 ```
 
 And then execute:
@@ -30,436 +34,226 @@ Or install it yourself as:
 gem install flows
 ```
 
-## Usage
+## Supported Ruby versions
 
-### `Flows::Flow`
+CI tests against last patch versions every day:
 
-Low-level instrument for defining execution flows. Used internally as execution engine for `Flows::Operation`.
-Check out source code and specs for details.
+* `MRI 2.5.x`
+* `MRI 2.6.x`
 
-### `Flows::Result`
+`MRI 2.7.x` will be added later, right now (`2.7.1`) this version of MRI Ruby is too
+unstable and produce segmentation faults inside RSpec internals.
 
-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).
+## Usage & Documentation
 
-Main concepts & conventions:
+* [YARD documentation](https://rubydoc.info/github/ffloyd/flows/master) - this
+  link is for master branch. You can also find YARD documentation for any released
+  version after `v0.4.0`. This documentation has a lot of examples, describes
+  motivation behind each abstraction, but lacks some guides and defined conventions.
+* [Guides](https://ffloyd.github.io/flows/#/) - guides, conventions, integration
+  and migration notes. Will be done before `v1.0.0` release. Right now is under development.
 
-* 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`
+## Development
 
-Basic usage:
+`Flows` is designed to be framework for your business logic. It is a big
+responsibility. That's why `flows` has near to be sadistic development
+conventions and linter setup.
 
-```ruby
-# create successful result with data {a: 1, b: 2}
-result_ok = Flows::Result::Ok.new(a: 1, b: 2)
+### Anyone can make Flows even better
 
-# get `:a` from result
-result_ok.unwrap[:a] # 1
+If you see some typos or unclear things in documentation or code - feel free to open
+an issue. Even if you don't have plans to implement a solution - a problem reporting
+will help development much. We cannot fix what we don't know.
 
-# get error data from result
-result_ok.error[:a] # raises exception
+### [Lefthook](https://github.com/Arkweid/lefthook) as a git hook manager
 
-# get status from result
-result_ok.status # :success
+Installation on MacOS via Homebrew:
 
-# boolean flags
-result_ok.ok? # true
-result_ok.err? # false
+```sh
+brew install Arkweid/lefthook/lefthook
+```
 
-# 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)
+Activation (in the root of the repo):
 
-# get status from result
-result_ok_custom.status # :custom
+```sh
+lefthook install
+```
 
-# create failure result with data {a: 1, b: 2}
-result_err = Flows::Result::Err.new(a: 1, b: 2)
+Run hooks manually:
 
-# get `:a` from result
-result_err.unwrap[:a] # raises exception
+```sh
+lefthook run pre-commit
+lefthook run pre-push
+```
 
-# get error data from result
-result_err.error[:a] # 1
+Please, never turn off the pre-commit and pre-push hooks.
 
-# get status from result
-result_err.status # :failure
+### Rubocop linter
 
-# boolean flags
-result_ok.ok? # false
-result_ok.err? # true
+[Rubocop](https://docs.rubocop.org/en/stable/) in this setup is responsible for:
 
-# 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)
+* defining code style (indentation, etc.)
+* suggest performance improvements ([rubocop-performance](https://docs.rubocop.org/projects/performance/en/stable/))
+* forces all that stuff (with some exceptions) to snippets in Markdown files ([rubocop-md](https://github.com/rubocop-hq/rubocop-md))
+* forces unit-testing best practices ([rubocop-rspec](https://docs.rubocop.org/projects/rspec/en/latest/))
 
-# get status from result
-result_err_custom.status # :custom
-```
+Rubocop config for library and RSpec files should be close to standard one only
+with minor amount of exceptions.
 
-Mixin `Flows::Result::Helpers` contains tools for simpler generating and matching Result Objects:
+Code in Markdown snippets and `/bin` folder can ignore more rules. `/bin` folder
+contains only development-related scripts and tools so it's ok to ease linter requirements.
 
-```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 = 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
-```
+Rubocop Metrics (ABC-size, method/class length, etc) must not be eased
+globally. Never.
 
-### `Flows::Operation`
+### Reek linter
 
-Let's solve simple task using operation:
+[Ruby Reek](https://github.com/troessner/reek) is a very aggressive linter that
+forces you to do a clean OOP design.
 
-* given numbers `a` and `b`
-* result should contain sum of this numbers
-* result should contain square of this sum
+You will be tempted to just shut up this linter many times. But believe me, in 9
+of 10 cases it worth to refactor. And after each such refactoring you will
+understand OOP design better and better.
 
-```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') 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: sum * sum)
-  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
-```
+### Rest of the linters
 
-#### Result Shapes
+* [MDL](https://github.com/markdownlint/markdownlint) - for consistent format of Markdown files
+* [forspell](https://github.com/kkuprikov/forspell) - for spellchecking in comments and markdown files
+* [inch](http://rrrene.org/inch/) - for documentation coverage suggestions (the
+  only optional linter)
 
-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:
+### Default Rake task and CI
 
-```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: %i[key1 key2],
-         status2: [:key3]
-
-# Failure shapes defined in the same way:
-err_shape :key1, :key2
-err_shape status1: %i[key1 key2],
-          status2: [:key3]
-```
+Default rake task (`bundle exec rake`) executes the following checks:
 
-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.
+* Rubocop
+* Ruby Reek
+* RSpec
+* Spellcheck (forspell)
+* MarkdownLint (mdl)
 
-#### Routing & Tracks
+CI is also performing default Rake task. So, if you want to reproduce CI error
+locally - just run `bundle exec rake`.
 
-You define side tracks, even nested ones:
+Default Rake task is also executed as a pre-push git hook.
 
-```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
-```
+### Error reporting
 
-In definition above tracks will not be used because there is no routes to this tracks. You may define routing like this:
+I hope no one will argue that clear errors makes development noticeably faster.
+That's why _each_ exception in `flows` should be clear and easy to read.
 
-```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, routes(
-  when_ok(:to_some_track) => :some_track
-)
-
-track :some_track do
-  step :inner * 1, routes(when_err => :inner_track) # redirect to inner_track on any failure result
-  track :inner_track do
-    step :deep_1, routes(when_ok(:some_status) => :outer_2) # you may redirect to steps too
-    step :deep_2
-  end
-  step :inner_2
-end
-
-step :outer_2
-```
+This cannot be tested automatically: you only can test correctness
+automatically, convenience can only be tested manually. That's why when you
+introduce any new `raise` you have to:
 
-You also can use less verbose, but shorter form of definition:
+* make an error message clear and descriptive
+* add this error to _errors demo CLI_ (`bin/errors`)
+* add this errors to _all the errors demo_ (`bin/all_the_errors`)
+* make sure that error is displayed correctly and follows a style of the rest
+  of implemented errors
 
-```ruby
-step :name,
-     match_ok(:status) => :track_name,
-     match_ok => :track_name
-```
+`bin/errors` is done using [GLI](https://davetron5000.github.io/gli/) library,
+run `bin/errors -h` to explore possibilities.
 
-Step has default routes:
+### Performance
 
-```ruby
-routes(
-  when_ok => next_step_name,
-  when_err => :term
-)
-```
+Ruby is slow. Moreover, Ruby is very slow. Yes, again. In the past time we had
+to compare Ruby with Python. Python was faster and that's why people started to
+complain about Ruby performance. That was fixed. But is Ruby fast nowadays? No.
+Because languages like Clojure, Go, Rust, Elixir appeared and in comparison
+with any of these languages Ruby is very very slow.
 
-Custom routes have bigger priority than default ones. Moreover, default routes can be overriden.
+That's why you **must** be extra careful with performance. Some business
+operations can be executed hundreds or even thousands times per request. Each
+line of code in your abstraction will slow down such request a bit. That's why
+you should think about each line performance.
 
-#### Lambda Steps
+Also, it's nearly impossible to make zero-cost abstractions in Ruby. The best
+thing you can do - to offload calculations to a class loading or initialization
+step. Sacrifice some warm-up time to make runtime performance better.
 
-You can use lambda for in-place step implementation:
+And to compare performance overhead between different `flows` abstractions
+and another alternatives a benchmarking CLI was done: `bin/benchmark`.
 
-```ruby
-step :name, ->(a:, b:, **) { ok(sum: a + b) }
-```
-
-#### Dependency Injection
+This CLI is done using GLI, run `bin/benchmark -h` to explore possibilities.
 
-You can override or inject step implementation on initialization:
-
-```ruby
-class Summator
-  include Flows::Operation
+So far, `flows` offers the best performance among alternatives. And this CLI
+is made to simplify comparison with alternatives and keep `flows` the fastest solution.
 
-  step :sum
+### Documentation
 
-  ok_shape :sum
-end
+Each public API method or module **must** be properly documented with examples
+and motivation behind.
 
-summator = Summator.new(deps: {
-                          sum: ->(a:, b:, **) { ok(sum: a + b) }
-                        })
+To run documentation server locally run `bin/docserver`.
 
-summator.call(a: 1, b: 2).unwrap[:sum] # 3
-```
+Respect `@since` YARD documentation tag. When some module, class or method has any
+API change - you have to provide correct `@since` tag value to the documentation.
 
-#### Wrapping steps
+### Documentation Driven Development
 
-You can wrap several steps with some logic:
+When you about to do some work, the following guideline can lead to the best
+results:
 
-```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
-```
+* first, write needed class and method structure without implementation
+* write YARD documentation with motivation and usage examples for each public
+  class, method, module.
+* write unit tests, check that tests are failing
+* write implementation until tests are green
 
-There is routing limitation when you use wrap:
+Yes, it's TDD approach with documentation step prepended.
 
-* 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
+### Unit test
 
-## Performance
+Each public API method or module **must** be properly tested. Internal modules
+can be tested indirectly through public API.
 
-You can compare performance for some cases by executing `bin/benchmark`. Examples for benchmark are presented in `bin/examples.rb`.
+Test coverage **must** be higher than 95%.
 
-`Flows::Operation` and `Dry::Trancation` may be executed in two ways:
+### Commit naming
 
-_Build once:_ when we create operation instance once (build operation):
+You **must** follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
-```ruby
-operation = OperationClass.new
+Allowed prefixes since `v0.4.0`:
 
-10_000.times { operation.call }
-```
+* `feat:` - for new features
+* `fix:` - for bugfixes
+* `perf:` - for performance improvements
+* `refactor:` - for refactoring work
+* `ci:` - updates for CI configuration
+* `docs:` - for documentation update
 
-_Build each time:_ when we create operation instance each execution:
+Sometimes commit can have several responsibilities. As example: when you write
+documentation, test and implementation for a feature in the one commit. You can do
+extra effort to split and rearrange commits to make it atomic. But does it
+really provide significant value if we already have a strong convention for
+changelog (see the next section)?
 
-```ruby
-10_000.times { OperationClass.new.call }
-```
+So, when you in such situation use the first applicable prefix in the list:
+between `docs` and `refactor` - pick `refactor`.
 
-`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
-```
+Also, there is one more special prefix for release commits. Release commit
+messages **must** look like: `release: v0.4.0`.
 
-## Development
+### Changelog
 
-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.
+Starting from `v0.4.0` [keep a changelog](https://keepachangelog.com/en/1.0.0/)
+guideline must be met.
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+If you adding something - provide some lines to the unreleased section of the `CHANGELOG.md`.
 
-## Contributing
+### Versioning
 
-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.
+The project strictly follows [SemVer](https://semver.org/spec/v2.0.0.html).
 
-## License
+After `v1.0.0` even smallest backward incompatible change will bump major
+version. _No exceptions._
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Commit with a version bump should contain _only_ version bump and CHANGELOG.md update.
 
-## Code of Conduct
+### Planned features for v1.0.0
 
-Everyone interacting in the Flows project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/ffloyd/flows/blob/master/CODE_OF_CONDUCT.md).
+* validation framework
+* error reporting improvements
+* various plugins for SCP (tracing, benchmarking, logging, etc)
+* site with guides and conventions