RubyGems - flows - Versions diffs - 0.1.0 → 0.5.1 - Mend

flows 0.1.0 → 0.5.1

Files changed (147) hide show

checksums.yaml +4 -4
data/.github/workflows/test.yml +38 -0
data/.gitignore +9 -1
data/.mdlrc +1 -0
data/.reek.yml +54 -0
data/.rubocop.yml +44 -2
data/.ruby-version +1 -1
data/.yardopts +1 -0
data/CHANGELOG.md +65 -0
data/README.md +186 -256
data/Rakefile +35 -1
data/bin/.rubocop.yml +5 -0
data/bin/all_the_errors +55 -0
data/bin/benchmark +69 -78
data/bin/benchmark_cli/compare.rb +118 -0
data/bin/benchmark_cli/compare/a_plus_b.rb +22 -0
data/bin/benchmark_cli/compare/base.rb +45 -0
data/bin/benchmark_cli/compare/command.rb +47 -0
data/bin/benchmark_cli/compare/ten_steps.rb +22 -0
data/bin/benchmark_cli/examples.rb +23 -0
data/bin/benchmark_cli/examples/.rubocop.yml +19 -0
data/bin/benchmark_cli/examples/a_plus_b/dry_do.rb +23 -0
data/bin/benchmark_cli/examples/a_plus_b/dry_transaction.rb +17 -0
data/bin/benchmark_cli/examples/a_plus_b/flows_do.rb +22 -0
data/bin/benchmark_cli/examples/a_plus_b/flows_railway.rb +13 -0
data/bin/benchmark_cli/examples/a_plus_b/flows_scp.rb +13 -0
data/bin/benchmark_cli/examples/a_plus_b/flows_scp_mut.rb +13 -0
data/bin/benchmark_cli/examples/a_plus_b/flows_scp_oc.rb +21 -0
data/bin/benchmark_cli/examples/a_plus_b/trailblazer.rb +15 -0
data/bin/benchmark_cli/examples/ten_steps/dry_do.rb +70 -0
data/bin/benchmark_cli/examples/ten_steps/dry_transaction.rb +64 -0
data/bin/benchmark_cli/examples/ten_steps/flows_do.rb +69 -0
data/bin/benchmark_cli/examples/ten_steps/flows_railway.rb +58 -0
data/bin/benchmark_cli/examples/ten_steps/flows_scp.rb +58 -0
data/bin/benchmark_cli/examples/ten_steps/flows_scp_mut.rb +58 -0
data/bin/benchmark_cli/examples/ten_steps/flows_scp_oc.rb +66 -0
data/bin/benchmark_cli/examples/ten_steps/trailblazer.rb +60 -0
data/bin/benchmark_cli/helpers.rb +12 -0
data/bin/benchmark_cli/ruby.rb +15 -0
data/bin/benchmark_cli/ruby/command.rb +38 -0
data/bin/benchmark_cli/ruby/method_exec.rb +71 -0
data/bin/benchmark_cli/ruby/self_class.rb +69 -0
data/bin/benchmark_cli/ruby/structs.rb +90 -0
data/bin/console +1 -0
data/bin/docserver +7 -0
data/bin/errors +130 -0
data/bin/errors_cli/contract_error_demo.rb +49 -0
data/bin/errors_cli/di_error_demo.rb +38 -0
data/bin/errors_cli/flow_error_demo.rb +22 -0
data/bin/errors_cli/flows_router_error_demo.rb +15 -0
data/bin/errors_cli/oc_error_demo.rb +40 -0
data/bin/errors_cli/railway_error_demo.rb +10 -0
data/bin/errors_cli/result_error_demo.rb +13 -0
data/bin/errors_cli/scp_error_demo.rb +17 -0
data/docs/.nojekyll +0 -0
data/docs/README.md +13 -0
data/docs/_sidebar.md +2 -0
data/docs/index.html +30 -0
data/flows.gemspec +27 -2
data/forspell.dict +17 -0
data/lefthook.yml +21 -0
data/lib/flows.rb +13 -5
data/lib/flows/contract.rb +402 -0
data/lib/flows/contract/array.rb +55 -0
data/lib/flows/contract/case_eq.rb +43 -0
data/lib/flows/contract/compose.rb +77 -0
data/lib/flows/contract/either.rb +53 -0
data/lib/flows/contract/error.rb +25 -0
data/lib/flows/contract/hash.rb +75 -0
data/lib/flows/contract/hash_of.rb +70 -0
data/lib/flows/contract/helpers.rb +22 -0
data/lib/flows/contract/predicate.rb +34 -0
data/lib/flows/contract/transformer.rb +50 -0
data/lib/flows/contract/tuple.rb +70 -0
data/lib/flows/flow.rb +96 -7
data/lib/flows/flow/errors.rb +29 -0
data/lib/flows/flow/node.rb +132 -0
data/lib/flows/flow/router.rb +29 -0
data/lib/flows/flow/router/custom.rb +59 -0
data/lib/flows/flow/router/errors.rb +11 -0
data/lib/flows/flow/router/simple.rb +25 -0
data/lib/flows/plugin.rb +14 -0
data/lib/flows/plugin/dependency_injector.rb +159 -0
data/lib/flows/plugin/dependency_injector/dependency.rb +24 -0
data/lib/flows/plugin/dependency_injector/dependency_definition.rb +16 -0
data/lib/flows/plugin/dependency_injector/dependency_list.rb +57 -0
data/lib/flows/plugin/dependency_injector/errors.rb +58 -0
data/lib/flows/plugin/implicit_init.rb +45 -0
data/lib/flows/plugin/output_contract.rb +85 -0
data/lib/flows/plugin/output_contract/dsl.rb +48 -0
data/lib/flows/plugin/output_contract/errors.rb +74 -0
data/lib/flows/plugin/output_contract/wrapper.rb +55 -0
data/lib/flows/plugin/profiler.rb +114 -0
data/lib/flows/plugin/profiler/injector.rb +35 -0
data/lib/flows/plugin/profiler/report.rb +48 -0
data/lib/flows/plugin/profiler/report/events.rb +43 -0
data/lib/flows/plugin/profiler/report/flat.rb +41 -0
data/lib/flows/plugin/profiler/report/flat/method_report.rb +81 -0
data/lib/flows/plugin/profiler/report/raw.rb +15 -0
data/lib/flows/plugin/profiler/report/tree.rb +98 -0
data/lib/flows/plugin/profiler/report/tree/calculated_node.rb +116 -0
data/lib/flows/plugin/profiler/report/tree/node.rb +35 -0
data/lib/flows/plugin/profiler/wrapper.rb +53 -0
data/lib/flows/railway.rb +154 -0
data/lib/flows/railway/dsl.rb +18 -0
data/lib/flows/railway/errors.rb +17 -0
data/lib/flows/railway/step.rb +24 -0
data/lib/flows/railway/step_list.rb +38 -0
data/lib/flows/result.rb +189 -2
data/lib/flows/result/do.rb +172 -0
data/lib/flows/result/err.rb +12 -6
data/lib/flows/result/errors.rb +29 -17
data/lib/flows/result/helpers.rb +25 -3
data/lib/flows/result/ok.rb +12 -6
data/lib/flows/shared_context_pipeline.rb +299 -0
data/lib/flows/shared_context_pipeline/dsl.rb +12 -0
data/lib/flows/shared_context_pipeline/dsl/callbacks.rb +38 -0
data/lib/flows/shared_context_pipeline/dsl/tracks.rb +52 -0
data/lib/flows/shared_context_pipeline/errors.rb +17 -0
data/lib/flows/shared_context_pipeline/mutation_step.rb +29 -0
data/lib/flows/shared_context_pipeline/router_definition.rb +21 -0
data/lib/flows/shared_context_pipeline/step.rb +44 -0
data/lib/flows/shared_context_pipeline/track.rb +54 -0
data/lib/flows/shared_context_pipeline/track_list.rb +51 -0
data/lib/flows/shared_context_pipeline/wrap.rb +74 -0
data/lib/flows/util.rb +17 -0
data/lib/flows/util/inheritable_singleton_vars.rb +86 -0
data/lib/flows/util/inheritable_singleton_vars/dup_strategy.rb +98 -0
data/lib/flows/util/inheritable_singleton_vars/isolation_strategy.rb +91 -0
data/lib/flows/util/prepend_to_class.rb +179 -0
data/lib/flows/version.rb +1 -1
metadata +288 -20
data/.travis.yml +0 -8
data/Gemfile.lock +0 -119
data/bin/demo +0 -66
data/bin/examples.rb +0 -159
data/bin/profile_10steps +0 -64
data/bin/ruby_benchmarks +0 -26
data/lib/flows/node.rb +0 -27
data/lib/flows/operation.rb +0 -54
data/lib/flows/operation/builder.rb +0 -130
data/lib/flows/operation/builder/build_router.rb +0 -37
data/lib/flows/operation/dsl.rb +0 -72
data/lib/flows/operation/errors.rb +0 -75
data/lib/flows/operation/executor.rb +0 -78
data/lib/flows/result_router.rb +0 -14
data/lib/flows/router.rb +0 -22

data/bin/errors_cli/railway_error_demo.rb ADDED

@@ -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 ADDED

@@ -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 ADDED

@@ -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/.nojekyll ADDED

File without changes

data/docs/README.md ADDED

@@ -0,0 +1,13 @@
+# Flows
+[![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.
+`flows` has no production dependencies so it can be used with any framework and cannot bring dependency incompatibilities.
+Rest of the documentation will be here when v1.0.0 be released.

data/docs/_sidebar.md ADDED

	@@ -0,0 +1,2 @@
1	+ * Overview
2	+ * [Getting Started](README.md)

data/docs/index.html ADDED

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <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">
+  <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
+</head>
+<body>
+  <div id="app">Please wait...</div>
+  <script>
+   window.$docsify = {
+     name: 'Flows',
+     repo: 'ffloyd/flows',
+     auto2top: true,
+     noEmoji: true,
+     loadSidebar: true,
+     subMaxLevel: 2
+   }
+  </script>
+  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
+  <script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
+  <script src="//unpkg.com/prismjs/components/prism-ruby.min.js"></script>
+  <script src="//unpkg.com/docsify-plantuml/dist/docsify-plantuml.min.js"></script>
+</body>
+</html>

data/flows.gemspec CHANGED

@@ -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,25 +21,50 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
+  # 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 ADDED

@@ -0,0 +1,17 @@
+# Format: one word per line. Empty lines and #-comments are supported too.
+# If you want to add word with its forms, you can write 'word: example' (without quotes) on the line,
+# where 'example' is existing word with the same possible forms (endings) as your word.
+# Example: deduplicate: duplicate
+linter
+linters
+matchers
+superset
+lefthook
+preprocessor
+postprocessor
+upcase
+fixpoint
+Megatron
+homebrew
+MDL
+forspell

data/lefthook.yml ADDED

@@ -0,0 +1,21 @@
+pre-commit:
+  parallel: true
+  commands:
+    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 CHANGED

@@ -1,13 +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/node'
-require 'flows/flow'
+require 'flows/util'
+require 'flows/plugin'
 require 'flows/result'
-require 'flows/operation'
+require 'flows/contract'
+require 'flows/flow'
+require 'flows/railway'
+require 'flows/shared_context_pipeline'

data/lib/flows/contract.rb ADDED

@@ -0,0 +1,402 @@
+require_relative 'contract/error'
+require_relative 'contract/case_eq'
+require_relative 'contract/predicate'
+require_relative 'contract/transformer'
+require_relative 'contract/compose'
+require_relative 'contract/either'
+require_relative 'contract/hash'
+require_relative 'contract/hash_of'
+require_relative 'contract/array'
+require_relative 'contract/tuple'
+require_relative 'contract/helpers'
+module Flows
+  # @abstract
+  #
+  # A type contract based on Ruby's case equality.
+  #
+  # ## Motivation
+  #
+  # In ruby we have limited ability to express type contracts.
+  # Because of the dynamic nature of the language we cannot provide type specs or signatures for methods.
+  # We can provide type specs in a form of YARD documentation, but in this way we have no real type checking.
+  # Nothing will stop execution if type contract is violated.
+  #
+  # Flows Contracts are designed to provide runtime type checks for critical places in your code.
+  # Let's review options we have except Flows Contracts and then define what is Flows Contract more strictly.
+  #
+  # Recently in the Ruby community, static/runtime type checking tools started to evolve.
+  # The most advanced solution right now is [Sorbet](https://sorbet.org/).
+  # But Sorbet solves a different problem: it provides static type checking for the whole codebase.
+  # Each method will be checked. Moreover, Sorbet is a tool like bundler or rake,
+  # not just a library.
+  #
+  # In contrast, Flows Contracts are designed to be used in critical places only.
+  # For example to declare input and output contracts for your service objects.
+  # Or to express contracts between application layers
+  # (between Data Access Layer and Business Logic Layer for example).
+  #
+  # As an optional feature Sorbet provides [runtime checks](https://sorbet.org/docs/runtime).
+  # And if you already using Sorbet you may use it to express type contracts also.
+  # The main differences between Sorbet Runtime and Flows Contracts are:
+  #
+  # * Contracts relies on Ruby's case equality and set of helper Contract classes for the most common cases.
+  #   Sorbet provides it's own type system and you have to learn it.
+  # * It may be overkill to use Sorbet for expressing contracts only.
+  #   In contrast, Flows Contracts are not designed to provide contract for each method in your codebase.
+  # * Sorbet Runtime checks should be a bit faster then Contracts checks (because of transformations).
+  # * The main advantage of Flows Contracts is _transformations_.
+  #   It allows you to slightly transform data using Contract
+  #   which adds some degree of flexibility to your entities.
+  #   See Tranformations section of this documentation for details.
+  #
+  # Let's check what we have for runtime type checking in pure Ruby.
+  # To make some runtime type checks we have at least two ways:
+  #
+  # * methods like `#is_a?`, `#kind_of?` and `#class` can check if subject is an instance of a particular class
+  # * case equality (`===`) in combination with `case` can check different things depends on concrete class.
+  #   Check [this article](https://blog.arkency.com/the-equals-equals-equals-case-equality-operator-in-ruby/)
+  #   for details.
+  #
+  # As you may see - case equality is already a contract check. We don't need additional checkers to test
+  # if something is a `String` because `String === x` will do the job.
+  # Also lambdas is like predicates with case equality.
+  # Ranges check if subject in a range and regular expressions check for string match.
+  # The problem is that `===` does not provide any error messages.
+  # Second problem - `===` is not an object - it's just a method.
+  # Contract should be an object, it opens more ways of composition.
+  #
+  # _So, Flows Contract is a case equality check wrapped into Contract class instance
+  # with assigned error message and optional transformation logic._
+  #
+  # ## Implementation
+  #
+  # {Contract} is an abstract class which requires {#check!} method
+  # to be implemented. It provides {#===}, {#check}, {#to_proc}, {#transform} and {#transform!} methods for usage in
+  # different scenarios. More details in the methods' documentation.
+  #
+  # {#transform!} must be overriden for types with defined transforming behaviour.
+  # By default no transformation defined - input will be equal to output.
+  # See Transformations and Transformation Laws sections of this documentation for details.
+  #
+  # ## Transformations
+  #
+  # Contract can be used in two ways:
+  #
+  # * to check if data matches a contract ({#check}, {#check!}, {#===}, {#to_proc})
+  # * to check & slightly transform data ({#transform}, {#transform!})
+  #
+  # Transformation is a way to slightly adjust input value before usage.
+  # Good example is when your method accepts both String and Symbol as a name for something,
+  # but internally name should always be a Symbol.
+  # So, contract for this case can be expressed in the following way:
+  #
+  # > Accept either String or Symbol, convert valid value to Symbol
+  #
+  # In this way we still can use both String and Symbol instances as argument,
+  # but in the method's implementation we can be sure that we always get Symbol.
+  #
+  # In the situation when you have to transform one or two arguments
+  # it's easier to merely rely on Ruby's methods like `#to_sym`, `#to_s`, etc.
+  # But in the cases when we talking about 3-6 arguments or nested arguments -
+  # contracts will be more convenient way to express transformations.
+  #
+  # ## Transformation Laws
+  #
+  # When you writing transformations for your contract you MUST implement it
+  # with respect to the following laws:
+  #
+  #     # let `c` be an any contract
+  #     # let `x` be an any value valid for `c`
+  #     # the following statements MUST be true
+  #
+  #     # 1. transformed value MUST match the contract:
+  #     c.check!(c.transform!(x)) == true
+  #
+  #     # 2. tranformation of transformed value MUST has no effect:
+  #     c.transform(x) == c.transform(c.transform(x))
+  #
+  # If you violate these laws - you'll get undefined behaviour of contracts.
+  #
+  # The meaning of these laws can be explained through [Equivalence Relation](https://en.wikipedia.org/wiki/Equivalence_relation).
+  # Let's use the following contract as example:
+  #
+  # > Accepts natural numbers except zero in form of String or Integer, transforms to Integer
+  #
+  # We can define a type using a set of all possible type values. For our contract such set can be
+  # described like `[1, '1', 2, '2', ...]`.
+  #
+  # First law says that transformation result must not leave a type.
+  # In other words: transformation is a function from contract type to contract type.
+  #
+  # Second law does two things:
+  #
+  # * split values of type into [equivalence classes](https://en.wikipedia.org/wiki/Equivalence_class)
+  # * for each equivalence class defines one and only one value which should be a transform result for
+  #   any value inside the equivalent class. You may call it a tranformation [fixpoint](https://en.wikipedia.org/wiki/Fixed_point_(mathematics)).
+  #
+  # In our example partition will look like this: `[[1, '1'], [2, '2'], ...]`.
+  # Each equivalence class consists of Integer and String form of the same natural number.
+  # And Integer form is a fixpoint.
+  #
+  # Let's review another example:
+  #
+  # > Accepts String, transform is `String#strip`
+  #
+  # In this example each equivalent class is a set of stripped string and all the possible non-stripped variations.
+  # Fixpoint is a stripped string.
+  #
+  # You may think about transformations as transformers (form cinema and animation).
+  # When transformer transforms - it's still the same guy, but in different form (first law).
+  # And fixpoint is transformer main form. We remember Megatron mostly as robot, not as truck. (second law)
+  #
+  # If you find contract transformation too complex abstraction - you can merely not use it.
+  # Flows Contracts without transforms become just type contracts.
+  #
+  # **You MUST be extra careful with transformations and {Compose}.
+  # You cannot just compose any set of types and get a correct result.
+  # See {Compose} documentation for details**
+  #
+  # ## Low-level contracts
+  #
+  # Flows provides some low-level contract classes.
+  # In almost all the cases you don't need to implement your own Contract class
+  # and you only need to compose your contract from this helper classes.
+  #
+  # Wrappers for Ruby objects:
+  #
+  # * {CaseEq} - to wrap Ruby's case equality with error message.
+  #   Automatically applied if you pass some Ruby object instead of
+  #   {Contract} to some contract initializer.
+  #   Please preserve such behaviour in custom contracts.
+  # * {Predicate} - to wrap lambda-check with error message
+  #
+  # Composition and modification of contracts:
+  #
+  # * {Transformer} - to wrap existing contract with some transformation
+  # * {Compose} - to merge two or more contracts
+  # * {Either} - to make "or"-contract from two or more provided contracts. (String or Symbol, for example)
+  #
+  # Contracts for common Ruby collection types:
+  #
+  # * {Hash} - restrict keys by some contract and values by another contract
+  # * {HashOf} - restrict values under particular keys by particular contracts
+  # * {Array} - restrict array elements with some contract
+  # * {Tuple} - restrict fixed-size array elements with contracts
+  #
+  # Using these classes as is can be too verbose and ugly when building complex contracts.
+  # To address this issue Contract class has singleton methods as shortcuts and {.make} class method as DSL:
+  #
+  #     # Accepts any string, transforms into stripped variant
+  #     strip_str = Flows::Contract.transformer(String, &:strip)
+  #
+  #     strip_str === 111
+  #     # => false
+  #
+  #     strip_str.transform!('  AAA  ')
+  #     # => 'AAA'
+  #
+  #     # Accepts positive integers
+  #     pos_int = Flows::Contract.compose(
+  #       Integer,
+  #       Flows::Contract.predicate('must be positive', &:positive?)
+  #     )
+  #
+  #     pos_int === 10
+  #     # => true
+  #
+  #     pos_int === -10
+  #     # => false
+  #
+  #     # Accepts numbers in String format
+  #     str_num = Flows::Contract.make do
+  #       compose(
+  #         String,
+  #         case_eq(/\A\d+\z/, 'must be a number')
+  #       )
+  #     end
+  #
+  #     # Accepts integer or number as string, transforms to integer
+  #     pos_int_from_str = transformer(either(Integer, str_num), &:to_i)
+  #
+  #     pos_int_from_str === 10
+  #     # => true
+  #
+  #     pos_int_from_str === '-10'
+  #     # => false
+  #
+  #     pos_int_from_str.transform!('10')
+  #     # => 10
+  #
+  #     pos_int_from_str.transform!(10)
+  #     # => 10
+  #
+  #     # Example of a complex contract
+  #     user_contract = Flows::Contract.make do
+  #       hash_of(
+  #         name: strip_str,
+  #         email: strip_str,
+  #         password_hash: String,
+  #         age: pos_int_from_str,
+  #         addresses: array(hash_of(
+  #           country: strip_str,
+  #           street: strip_str
+  #         ))
+  #       )
+  #     end
+  #
+  #     result = user_contract.transform!(
+  #       name: '  Roman ',
+  #       email: 'bla@blabla.com',
+  #       password_hash: '01234567890ABCDEF',
+  #       age: '10',
+  #       addresses: [],
+  #       blabla: 'blablabla' # extra field will be removed by HashOf#transform
+  #     )
+  #
+  #     result == {
+  #       name: 'Roman',
+  #       email: 'bla@blabla.com',
+  #       password_hash: '01234567890ABCDEF',
+  #       age: 10,
+  #       addresses: []
+  #     }
+  #
+  # All the shortcuts (without {.make}) are available as a separate module: {Helpers}.
+  #
+  # It's up to lead developer how to integrate contracts into app.
+  # You may put contract into constant and use it in the first line of your method.
+  # Or you can write some DSL.
+  # But you should avoid constructing static contracts at runtime -
+  # it's better to instantiate them during loading time (by putting it into constant, for example).
+  #
+  # {Flows::Plugin::OutputContract} in combination with {SharedContextPipeline} will add DSL for contracts.
+  # So, you don't need to invent anything to use output contracts with shared context pipelines.
+  #
+  # ## Private helper methods
+  #
+  # Some private utility methods are defined to simplify new contract implementations:
+  #
+  # `to_contract(value) => Flows::Contract` - if value is a Contract does nothing.
+  # Otherwise wraps value with {CaseEq}. Useful in initializers.
+  #
+  # `merge_nested_errors(description, nested_error) => String` - to make an accurate
+  # multiline error messages with indentation.
+  #
+  # @!method check!( other )
+  #   @abstract
+  #   Checks for type match.
+  #   @return [true] `true` if check succesful
+  #   @raise [Flows::Contract::Error] if check failed
+  class Contract
+    # Case equality check.
+    #
+    # Based on {#check!}
+    #
+    # @example Contracts and Ruby's case
+    #
+    #     case value
+    #     when contract1 then blablabla
+    #     when contract2 then blablabla2
+    #     end
+    #
+    # @return [Boolean] check result
+    def ===(other)
+      check!(other)
+      true
+    rescue Flows::Contract::Error
+      false
+    end
+    # Checks `other` for type match.
+    #
+    # Based on {#check!}.
+    #
+    # @param other [Object] object to check
+    # @return [Flows::Result::Ok<true>] if check successful
+    # @return [Flows::Result::Err<String>] if check failed
+    def check(other)
+      check!(other)
+      Result::Ok.new(true)
+    rescue ::Flows::Contract::Error => err
+      Result::Err.new(err.value_error)
+    end
+    # Check and transform value.
+    #
+    # Override this method to implement type transform behaviour.
+    #
+    # If contract is built from other contracts -
+    # all internal contracts must be called via {#transform}.
+    #
+    # You must obey Transformation Laws (see {Contract} class documentation).
+    #
+    # @return [Object] successful result with value after transformation
+    # @raise [Flows::Contract::Error] if check failed
+    def transform!(other)
+      check!(other)
+      other
+    end
+    # Check and transform value.
+    #
+    # Based on {#transform!}.
+    #
+    # @return [Flows::Result::Ok<Object>] successful result with value after type transform
+    # @return [Flows::Result::Err<String>] failure result with error message
+    def transform(other)
+      Result::Ok.new(transform!(other))
+    rescue ::Flows::Contract::Error => err
+      Result::Err.new(err.value_error)
+    end
+    # Allows to use contract as proc.
+    #
+    # Based on {#===}.
+    #
+    # @example Check all elements in an array
+    #     pos_num = Flows::Contract::Predicate.new 'must be positive' do |x|
+    #       x > 0
+    #     end
+    #
+    #     [1, 2, 3].all?(&pos_num)
+    #     # => true
+    def to_proc
+      proc do |obj|
+        self === obj # rubocop:disable Style/CaseEquality
+      end
+    end
+    class << self
+      include Helpers
+      # @example
+      #     Flows::Contract.make { transformer(either(Symbol, String), &:to_sym) }
+      #
+      #     Flows::Contract.make { String }
+      def make(&block)
+        result = instance_exec(&block)
+        result.is_a?(Contract) ? result : CaseEq.new(result)
+      end
+    end
+    private
+    # :reek:UtilityFunction
+    def to_contract(value)
+      value.is_a?(::Flows::Contract) ? value : CaseEq.new(value)
+    end
+    # :reek:UtilityFunction
+    def merge_nested_errors(description, nested_errors)
+      shifted = nested_errors.split("\n").map { |str| '    ' + str }.join("\n")
+      description + "\n" + shifted
+    end
+  end
+end