flows 0.2.0 → 0.6.0

data/bin/errors_cli/oc_error_demo.rb

@@ -0,0 +1,40 @@
+module OCErrorDemo
+  class WithoutContract
+    include Flows::Plugin::OutputContract
+  end
+
+  class WithContract
+    include Flows::Plugin::OutputContract
+
+    success_with :ok do
+      hash_of(
+        x: Integer,
+        y: Integer
+      )
+    end
+
+    def call(result)
+      result
+    end
+  end
+
+  class << self
+    include Flows::Result::Helpers
+
+    def no_contract
+      WithoutContract.new
+    end
+
+    def contract_error
+      WithContract.new.call(ok(z: 100))
+    end
+
+    def status_error
+      WithContract.new.call(ok(:unexpeted_status, x: 1, y: 2))
+    end
+
+    def result_type_error
+      WithContract.new.call(z: 100)
+    end
+  end
+end

data/bin/errors_cli/railway_error_demo.rb

@@ -0,0 +1,10 @@
+module RailwayErrorDemo
+  class MyRailway < ::Flows::Railway
+  end
+
+  class << self
+    def call
+      MyRailway.new
+    end
+  end
+end

data/bin/errors_cli/result_error_demo.rb

@@ -0,0 +1,13 @@
+module ResultErrorDemo
+  class << self
+    include Flows::Result::Helpers
+
+    def success_access_error
+      ok(some: :data).error
+    end
+
+    def failure_access_error
+      err(some: :data).unwrap
+    end
+  end
+end

data/bin/errors_cli/scp_error_demo.rb

@@ -0,0 +1,17 @@
+module SCPErrorDemo
+  class MySCP < ::Flows::SharedContextPipeline; end
+
+  class NoImplSCP < ::Flows::SharedContextPipeline
+    step :hello
+  end
+
+  class << self
+    def no_steps
+      MySCP.new
+    end
+
+    def no_step_impl
+      NoImplSCP.new
+    end
+  end
+end

data/docs/README.md

@@ -1,197 +1,13 @@
 # Flows
 
-[![Build Status](https://github.com/ffloyd/flows/workflows/Build/badge.svg)](https://github.com/ffloyd/flows/actions)
+[![Build Status](https://github.com/ffloyd/flows/workflows/Test/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).
+but has simpler and flexible DSLs for defining operations and matching results. Also `flows` is faster.
 
 `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).
+Rest of the documentation will be here when v1.0.0 be released.

data/docs/_sidebar.md

@@ -1,26 +1,2 @@
 * Overview
   * [Getting Started](README.md)
-  * [Performance](overview/performance.md)
-
-* Result Objects
-  * [Basic Usage](result_objects/basic_usage.md)
-  * [Do Notation](result_objects/do_notation.md)
-
-* Railway
-  * [Basic Usage](railway/basic_usage.md)
-
-* Operation
-  * [Basics](operation/basic_usage.md)
-  * [Result Shapes](operation/result_shapes.md)
-  * [Routing & Tracks](operation/routing_tracks.md)
-  * [Lambda Steps](operation/lambda_steps.md)
-  * [Inject Steps](operation/inject_steps.md)
-  * [Wrapping Steps](operation/wrapping_steps.md)
-
-* Flow
-  * [General Idea](flow/general_idea.md)
-  * [Direct Usage](flow/direct_usage.md)
-
-* Contributing
-  * [Local Development](contributing/local_development.md)
-  * [Benchmarks & Profiling](contributing/benchmarks_profiling.md)

data/docs/index.html

@@ -2,7 +2,7 @@
 <html lang="en">
 <head>
   <meta charset="UTF-8">
-  <title>Flows</title>
+  <title>Flows - framework for your Business Logic Layer</title>
   <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
   <meta name="description" content="Flows documentation">
   <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">

data/flows.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.authors       = ['Roman Kolesnev']
   spec.email         = ['rvkolesnev@gmail.com']
 
-  spec.summary       = 'Ruby framework for building FSM-like data flows.'
+  spec.summary       = 'Ruby framework for building your Business Logic Layer inside Rails and other frameworks.'
   spec.homepage      = 'https://github.com/ffloyd/flows'
   spec.license       = 'MIT'
 
@@ -21,27 +21,52 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
+  spec.required_ruby_version = '>= 2.5'
+
+  # This library has no production dependencies.
+  # So, it will not block you from updating any dependencies in your project.
+  # So, don't add production dependencies.
+
+  # things that should be part of a standard library
   spec.add_development_dependency 'bundler', '~> 2.0'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
 
+  # Documentation is the key!
+  spec.add_development_dependency 'yard'
+
+  # linters to make code and documentation awesome
   spec.add_development_dependency 'forspell', '~> 0.0.8'
+  spec.add_development_dependency 'inch'
+  spec.add_development_dependency 'mdl'
+  spec.add_development_dependency 'reek'
   spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'rubocop-md'
   spec.add_development_dependency 'rubocop-performance'
   spec.add_development_dependency 'rubocop-rspec'
 
+  # let's make dubugging confortable
+  spec.add_development_dependency 'awesome_print'
   spec.add_development_dependency 'pry'
 
+  # 100% coverage does not mean that you cover everything,
+  # but 50% coverage means that you haven't covered half of the project.
   spec.add_development_dependency 'codecov'
   spec.add_development_dependency 'simplecov'
 
   # benchmarking tools
   spec.add_development_dependency 'benchmark-ips'
+  spec.add_development_dependency 'kalibera'
   spec.add_development_dependency 'ruby-prof'
   spec.add_development_dependency 'stackprof'
 
+  # make benchmark scripts a convinient CLI tool
+  spec.add_development_dependency 'gli'
+  spec.add_development_dependency 'rainbow'
+  spec.add_development_dependency 'warning' # to suppress some unhandable Ruby warnings during CLI execution
+
   # alternatives for comparison in benchmarking
+  spec.add_development_dependency 'dry-monads', '~> 1.3'
   spec.add_development_dependency 'dry-transaction'
   spec.add_development_dependency 'trailblazer-operation'
 end

data/forspell.dict

@@ -6,3 +6,12 @@ linter
 linters
 matchers
 superset
+lefthook
+preprocessor
+postprocessor
+upcase
+fixpoint
+Megatron
+homebrew
+MDL
+forspell

data/lefthook.yml

@@ -4,9 +4,18 @@ pre-commit:
     rubocop:
       glob: "{*.rb,*.md,*.gemspec,Gemfile,Rakefile}"
       run: bundle exec rubocop {staged_files}
+    reek:
+      glob: "*.rb"
+      exclude: "^spec|^bin"
+      run: bundle exec reek {staged_files}
     markdownlinter:
       glob: "*.md"
       run: bundle exec mdl {staged_files}
     forspell:
       glob: "{*.md,*.rb}"
       run: bundle exec forspell {staged_files}
+
+pre-push:
+  commands:
+    test:
+      run: bundle exec rake

data/lib/flows.rb

@@ -1,15 +1,21 @@
+# Namespace for all the classes and modules of the library.
+#
+# @since 0.4.0
 module Flows
+  # Base class for all the library's errors.
+  #
+  # @since 0.4.0
   class Error < StandardError; end
 end
 
 require 'flows/version'
 
-require 'flows/router'
-require 'flows/result_router'
+require 'flows/util'
+require 'flows/plugin'
 
-require 'flows/node'
+require 'flows/result'
+require 'flows/contract'
 require 'flows/flow'
 
-require 'flows/result'
 require 'flows/railway'
-require 'flows/operation'
+require 'flows/shared_context_pipeline'