mayak 0.2.0 → 0.2.2

data/lib/mayak/monads/README.md

@@ -1,1364 +0,0 @@
-# Monads
-
-## Table of Contents
-* [Description](#description)
-* [Maybe](#maybe)
-* [Try](#try)
-* [Result](#result)
-
-## Description
-
-This module is introduced to replace `dry-monads` with custom monads implementation which plays better with sorbet
-type-checking. If you haven't worked with monads and don't know what's that, check [dry-monads documentation](https://dry-rb.org/gems/dry-monads/1.3/) first.
-This should help you to get an idea of monads.
-
-Now let's dive deeper into different kinds of monads.
-
-## Maybe
-
-This is probably the simplest monad that represents a series of computations could return `nil` at any point.
-This monad is [parameterized](https://sorbet.org/docs/generics) with a type of value. Basically, the `Maybe` is supertype
-of two subtypes: `Some` and `None` that shares the same interface. `Some` subtype contains a value, `None` doesn't contain
-anything and represents `nil`.
-
-### Initialization
-
-The monad can be created with two primary constructors `Maybe` and `None` (note that these are methods).
-Method `#Maybe` wraps a nilable value with a `Maybe` class: if a value is nil, than it returns value of `None`,
-if the value is present, it returns instance of `Some`. In order to access these helpers`Mayak::Monads::Maybe::Mixin` must be included first:
-
-```ruby
-include Mayak::Monads::Maybe::Mixin
-
-sig { params(numbers: T::Array[Integer]).returns(T.nilable(Integer)) }
-def first(numbers)
-  numbers.first
-end
-
-Maybe(first[])  # None
-Maybe(first[1]) # Some[Integer](value = 1)
-```
-
-Also, the monad can be instantiated directly with `Mayak::Monads::Maybe::Some` and `Mayak::Monads::Maybe::None`:
-
-```ruby
-sig { returns(Mayak::Monads::Maybe[Integer]) }
-def some
-  Mayak::Monads::Maybe::Some[Integer].new(10)
-end
-
-sig { returns(Mayak::Monads::Maybe[Integer]) }
-def none
-  Mayak::Monads::Maybe::None[Integer].new
-end
-```
-
-### Unpacking
-
-In order to retrieve a value from a `Maybe` a method `#value` which is defined on `Mayak::Monads::Maybe::Some` can be used.
-`Mayak::Monads::Maybe::Some` is a subtask of `Maybe`. Note that the accessor is only defined on `Some` subtype, so if the `#value`
-method will be called on an instance of `Maybe`, Sorbet will not type-check, since `Maybe` doesn't have this method.
-In order to access value of `Maybe`, it need to be verified first that the monad is instance of `Some`, and only after that
-this method can invoked. The most convenient way to do this is to use case-when statement.
-
-```ruby
-sig { params(a: Integer, b: Integer).returns(Mayak::Monads::Maybe[Integer]) }
-def divide(a, b)
-  if b == 0
-    None()
-  else
-    Maybe(a / b)
-  end
-end
-
-sig { params(a: Integer, b: Integer).void }
-def print_result_divide(a, b)
-  result = divide(a, b)
-  case result
-  when Mayak::Monads::Maybe::Some
-    # sorbet's flow-typing down-casts result to Mayak::Monads::Maybe::Some
-    # so type of this variable is Mayak::Monads::Maybe::Some in this branch
-    puts "#{a} / #{b} = #{result.value}"
-  when Mayak::Monads::Maybe::None
-    puts "Division by zero"
-  else
-    T.absurd(result)
-  end
-end
-
-print_result_divide(10, 2) # 10 / 2 = 5
-print_result_divide(10, 0) # Division by zero
-```
-
-The other way is to use method `#value_or` which returns either a value if the monad is `Some`, or
-fallback value if the monad is `None`:
-
-```ruby
-divide(10, 2).value_or(0) # 5
-divide(10, 0).value_or(0) # 0
-```
-
-Note that the type of value passed into `value_or` shouldn't necessarily be of the same type as `Maybe`. If it doesn't match
-the result type of method invokation will be union of `Maybe` type and type of value passed:
-```ruby
-result = divide(10, 2).value_or("None")
-T.reveal_type(result) # T.any(String, Integer)
-```
-
-You can also pass `nil` into `value_or`, and the result type of the expression will `T.nilable` type:
-```ruby
-result = divide(10, 2).value_or(nil)
-T.reveal_type(result) # T.nilable(Integer)
-```
-
-### Methods
-
-#### `#either`
-
-Receives two lambda functions representing branches: none-branch, and some-branch. If a `Maybe` is `None` than none-branch will be executedand result of method invokation will be a result of none-branch execution. If a `Maybe` is `Some` than some-branch will be executed with a value of monad and result of method invokation will be a result of some-branch execution.
-
-```ruby
-divide(10, 2).either(
-  -> { 0 },
-  -> (value) { value * 100 }
-) # 50
-
-
-divide(10, 0).either(
-  -> { 0 },
-  -> (value) { value * 100 }
-) # 0
-
-result = divide(10, 0).either(
-  -> { "Error" },
-  -> (value) { value * 100 }
-)
-T.reveal_type(result) # T.any(String, Integer)
-```
-
-#### `#map`
-
-The same as `fmap` in a dry-monads `Maybe`. Allows to modify the value inside the `Maybe` with a block if it's present. Returns `Maybe` itself.
-
-```ruby
-sig { returns(Mayak::Monads::Maybe[Integer]) }
-def some
-  Mayak::Monads::Maybe::Some[Integer].new(10)
-end
-
-sig { returns(Mayak::Monads::Maybe[Integer]) }
-def none
-  Mayak::Monads::Maybe::None[Integer].new
-end
-
-some.map { |a| a + 20 } # Some[Integer](value = 20)
-none.map { |a| a + 20 } # None[Integer]
-```
-
-#### `#flat_map`
-The same as `bind` in a dry-monads `Maybe`. Allows to modify the value with a block that returns another `Maybe`
-if it's present, otherwise returns `None`. If the block returns `None`, the whole computation returns `None`.
-
-```ruby
-sig { params(a: Integer, b: Integer).returns(Mayak::Monads::Maybe[Integer]) }
-def divide(a, b)
-  if b.zero?
-    Mayak::Monads::Maybe::None[Integer].new
-  else
-    Mayak::Monads::Maybe::Some[Integer].new(a / b)
-  end
-end
-
-divide(20, 2).flat_map { |a| divide(a, 2) } # Some[Integer](value = 5)
-divide(20, 2).flat_map { |a| divide(a, 0) } # None
-divide(20, 0).flat_map { |a| divide(a, 2) } # None
-```
-
-#### `#filter`
-
-Receives a block the returns a boolean value and checks the underlying value with the block when a monad is `Some`.
-Returns `None` if the block called on the value returns `false`, and returns `self` if the block returns `true`.
-Returns `None` if the monad is `None`.
-
-```ruby
-divide(20, 2).filter { |value| value > 5 } # Some[Integer](value = 10)
-divide(20, 2).filter { |value| value < 5 } # None
-divide(20, 0).filter { |value| value < 5 } # None
-```
-
-#### `#some?`
-
-Returns true if a `Maybe` is a `Some` and false if it's `None`.
-
-```ruby
-divide(20, 2).some? # true
-divide(20, 0).some? # false
-```
-
-#### `#none?`
-
-Returns true if a `Maybe` is a `None` and false if it's `Some`.
-
-```ruby
-divide(20, 2).none? # false
-divide(20, 0).none? # true
-```
-
-#### `#value_or`
-
-Unpack a `Maybe` and returns its value if it's a `Some`, or returns provided fallback value if it's a `None`.
-
-```ruby
-divide(20, 2).value_or(0) # 10
-divide(20, 0).value_or(0) # 0
-```
-
-#### `#to_task`
-
-Converts a value to task. If a `Maybe` is an instance of `Some`, it returns succeeded task, if it's a `None`,
-it returns failed task with a provided error.
-
-```ruby
-task = Mayak::Concurrent::Task.execute { 100 }
-error = StandardError.new("Division by zero")
-task.flat_map { |value| divide(value, 10).to_task(error) }.await! # 10
-task.flat_map { |value| divide(value, 0).to_task(error) }.await!  # StandardError: Divison by zero
-```
-
-#### `#to_result`
-
-Converts a `Maybe` into a `Result`. If the `Maybe` is a `Some`, returns `Result::Success` with a value of the `Maybe`.
-If it's a `None`, returns `Result::Failre` with a value of an error provided as an argument.
-
-```ruby
-divide(10, 2).to_result("Division by zero") # Success: Result[String, Integer](value = 5)
-divide(10, 0).to_result("Division by zero") # Failure: Result[String, Integer](error = "Division by zero")
-```
-
-#### `#to_try`
-
-Converts a `Maybe` into a `Try`. If the `Maybe` is a `Some`, returns `Try::Success` with a value of the `Maybe`.
-If it's a `None`, returns `Try::Failre` with a value of an error provided as an argument.
-
-```ruby
-divide(10, 2).to_try(StandardError.new("Division by zero")) # Success: Try[Integer](value = 5)
-divide(10, 0).to_try(StandardError.new("Division by zero")) # Failure: Try[Integer](error = StandardError(message = "Division by zero"))
-```
-
-Combination of `Maybe` constructor with `#to_try` method allows to significantly simplify common
-pattern: checking nullability of a value, and returning error if the value is missing:
-```ruby
-sig { params(user: User).returns(Try[Address]) }
-def get_address(user)
-  address = user.contact.address
-
-  if address.present?
-    Success(address)
-  else
-    Failure(AddressMissingError.new("Missing address for User(id=#{user.id})"))
-  end
-end
-```
-
-With `Maybe` and `#to_try`:
-
-```ruby
-sig { params(user: User).returns(Try[Address]) }
-def get_address(user)
-  Maybe(user.contact.address).to_try(
-    AddressMissingError.new("Missing address for User(id=#{user.id})")
-  )
-end
-```
-
-#### `#tee`
-
-If a `Maybe` is an instance of `Some`, runs a block with a value of `Some` passed, and returns the monad itself
-unchanged. Doesn't do anything if it's a `None`.
-
-```ruby
-divide(10, 2).tee { |a| puts a }
-# returns: Some[Integer](value = 5)
-# console: 5
-
-divide(10, 0).tee { |a| puts a }
-# returns: None
-```
-
-Can be useful to embed side-effects into chain of monad transformation:
-```ruby
-sig { params(a: Integer, b: Integer).returns(Maybe[String]) }
-def run(a, b)
-  divide(a, b)
-    .tee { |value| logger.info("#{a} / #{b} = #{value}") }
-    .map { |value| value * 100 }
-    .tee { |value| logger.info("Intermediate result = #{value}") }
-    .map(&:to_s)
-end
-```
-
-#### `#recover`
-
-Converts `None` into a `Some` with a provided value. If the monad is an instance of `Some`, returns itself.
-
-```ruby
-divide(10, 2).recover(0) # Some[Integer](value = 5)
-divide(10, 0).recover(0) # Some[Integer](value = 0)
-```
-
-#### `.sequence`
-`Maybe.sequence` takes an array of `Maybe`s and transform it into a `Maybe` of an array.
-If all elements of an argument array is `Some`, then result will be `Some` of the array, otherwise
-it will `None`.
-
-```ruby
-values = [Maybe(1), Maybe(2), Maybe(3)]
-Maybe.sequence(values) # Some([10, 5, 3])
-
-values = values = [Maybe(nil), Maybe(2), Maybe(3)]
-Maybe.sequence(values) # None
-```
-
-#### `.check`
-
-Receives a value and block returning a boolean value. If the block returns true,
-the method returns the value wrapped in `Some`, otherwise it returns `None`:
-
-```ruby
-Maybe.check(10) { 20 > 10 } # Some[Integer](10)
-Maybe.check(20) { 10 > 20 } # None
-```
-
-#### `.guard`
-
-Receives a block returning a boolean value. If the block returns true,
-the method returns a `Some` containing `nil`, otherwise `None` is returned:
-
-```ruby
-Maybe.guard { 20 > 10 } # Some[NilClass](nil)
-Maybe.guard { 10 > 20 } # None
-```
-
-### Do-notation
-
-Using `map` and `flat_map` for monads chaining can be really tedious, especially when computation
-requires combining different values from branches.
-
-Let's take a look at the following code snippet.
-
-```ruby
-sig { abstract.params(id: Integer).returns(Maybe[User]) }
-def fetch_user(id)
-end
-
-sig { abstract.params(city: String, address: Address).returns(Maybe[Coordinates]) }
-def fetch_city_coordinates(city, address)
-end
-
-sig { abstract.params(user: User, coordinates: Coordinates).returns(Maybe[UserAddressCache]) }
-def fetch_user_address_cache(user, coordinates)
-end
-
-sig {
-  abstract
-    .params(user: User, address: Address, coordinates: Coordinates, cache: UserAddressCache)
-    .returns(Maybe[UserAddressData])
-}
-def build_user_address_data(user, address, coordinates, cache)
-end
-
-sig { params(user_id: Integer).returns(Maybe[UserAddressData]) }
-def run(user_id)
-  fetch_user(user_id).flat_map { |user|
-    user
-      .address
-      .flat_map { |address|
-        address
-          .city
-          .flat_map { |city| fetch_city_coordinates(city) }
-          .flat_map { |coordinates|
-            fetch_user_address_cache(user, coordinates).flat_map { |cache|
-              build_user_address_data(user, address, coordinates, cache)
-            }
-          }
-      }
-  }
-end
-```
-
-Don't worry if you can't really understand what's going on here, the code is intentionally overcomplicated to show you
-to which extremes `#map` and `#flat_map` can lead.
-
-In order to simplify computation you can use Do-notation. Let's see the same `run` method with using
-Do-notation instead of `#map` and `#flat_map` chaining, and let's break down how it's work:
-
-```ruby
-# Make sure you have the Mixin included
-include Mayak::Monads::Maybe::Mixin
-
-sig { params(user_id: Integer).returns(Maybe[UserAddressCache]) }
-def run(user_id)
-  for_maybe {
-    user        = do_maybe! fetch_user(user_id)
-    address     = do_maybe! user.address
-    city        = do_maybe! address.city
-    coordinates = do_maybe! fetch_city_coordinates(city)
-    cache       = do_maybe! fetch_user_address_cache(user, coordinates)
-    do_maybe! build_user_address_data(user, address, coordinates, cache)
-  }
-end
-```
-
-Do-notation basically consists from two methods `for_maybe` and `do_maybe!`. `for_maybe` creates
-a Do-notation scope within which you can use `do_maybe!` to unpack Monad values. If `do_maybe!` receives
-a `Some` value, it unpacks it and returns underlying values, if it receives a `None`, it short circuits execution,
-and the whole `for_maybe` block returns `None`. Otherwise `for_maybe` returns result of the last
-expression wrapped into `Maybe`.
-
-Let's check a few examples:
-
-```ruby
-result = for_maybe {
-  a = do_maybe! Maybe(10)
-  puts a # Prints: 10
-  b = do_maybe! Maybe(20)
-  puts b # Prints: 20
-  a + b
-}
-result # Some[Integer](value = 30)
-
-failure = for_maybe {
-  a = do_maybe! Maybe(10)
-  b = do_maybe! None # stops execution here
-  puts "Not getting here" # Doesn't print anything
-  a + b
-}
-failure # None
-```
-You can also you methods `check_maybe!` and `guard_maybe!` to assert some invariants
-in do-notation blocks. These methods are specialized helpers of `Maybe.check` and `Maybe.guard` for
-more convenient usage in do-notation blocks:
-
-```ruby
-user = for_maybe {
-  user    = do_maybe! fetch_user(user_id)
-  company = do_maybe! fetch_company(company_id)
-  # abrupt execution if block returns false
-  # or return user if block returns false
-  #
-  # semantically equivalent to:
-  # if user.works_in?(company)
-  #   do_maybe! Some(user)
-  # else
-  #   do_maybe! None.new
-  # end
-  check_maybe!(user) { user.works_in?(company) }
-}
-
-for_maybe {
-  api_key = do_maybe! Maybe(params[:api_key])
-  # abrupt execution if block returns None
-  #
-  # semantically equivalent to:
-  # if validate_api_key(api_key)
-  #   do_maybe! Some(nil)
-  # else
-  #   do_maybe! None.new
-  # end
-  guard_maybe! { validate_api_key(api_key) }
-
-  perform_query
-}
-```
-
-A major improvement upon `dry-monads` do-notation, is that `Mayak::Monad`s do-notation if fully typed.
-Do-notations infers both result type of the whole computation, and a type of a value unwrapped by `do_maybe!`
-
-```ruby
-for_maybe {
-  value = do_maybe! Maybe(10)
-  T.reveal_type(value)
-  value
-}
-# > Revealed type: Integer
-
-result = for_maybe {
-  value = do_maybe! Maybe(10)
-  value
-}
-T.reveal_type(result)
-# > Revealed type: Integer
-```
-
-## Try
-
-`Try` monad represents result of a computation that can succeed with an arbitrary value, or fail with an error of a subtype of `StandardError`.
-`Try` has two subtypes: `Failure` which contains an instance of subtype of `StandardError` and represents failure case,
-and `Success`, which contains a success value of given type.
-
-### Initialization
-
-The primary way to create an instance of `Try` is to use constructor method `#Try` from `Mayak::Monads::Try::Mixin`.
-This method receives a block that may raise exceptions. If an exception has been raised inside the block,
-the method will return instance of `Try::Failure` containing an error. Otherwise the method will return result of the block
-wrapped into `Try::Success`
-
-```ruby
-include Mayak::Monads::Try::Mixin
-
-Try { 10 } # Try::Success[Integer](@value=10)
-Try {
-  a = "Hello "
-  b = "World!"
-  a + b
-} # Try::Success[String](@value="Hello World!")
-
-Try {
-  a = 10
-  b = 0
-  a / b
-} # Try::Failure[Integer](@failure=#<ZeroDivisionError: divided by 0>)
-```
-
-Note that constructor is able to infer a type of value from type returned from the block:
-
-```ruby
-sig { params(a: Integer, b: Integer).returns(Try[Integer]) }
-def divide(a, b)
-  Try { a / b }
-end
-```
-
-Exception should be an instance of `StandardError`s subtype to be captured:
-```ruby
-Try { raise Exception.new("Not going to be captured") }
-# > Exception: Not going to be captured
-```
-
-`#Try` can receive types of arguments to be captured. If exceptions of other types were raised, they won't
-captured. Types of exceptions should be subtypes of `StandardError`:
-
-```ruby
-class CustomError < StandardError
-end
-
-Try(CustomError) {
-  raise CustomError.new
-} # Try::Failure[T.noreturn](@failure=#<CustomError: CustomError>)
-
-Try(CustomError) {
-  raise StandardError.new("Not going to be captured")
-}
-# > StandardError: Not going to be captured
-```
-
-`Try` allows to specify multiple error types:
-```ruby
-class CustomError1 < StandardError
-end
-
-class CustomError2 < StandardError
-end
-
-Try(CustomError1, CustomError2) {
-  raise CustomError1.new
-} # Try::Failure[T.noreturn](@failure=#<CustomError: CustomError>)
-
-Try(CustomError1, CustomError2) {
-  raise CustomError2.new
-} # Try::Failure[T.noreturn](@failure=#<CustomError: CustomError>)
-
-Try(CustomError1, CustomError2) {
-  raise StandardError.new("Not going to be captured")
-}
-# > StandardError: Not going to be captured
-```
-
-`Try` can also be initialized directly be invoking constructors of its subtypes:
-```ruby
-Mayak::Monads::Try::Success[Integer].new(10) # Try::Success[Integer](@value=10)
-Mayak::Monads::Try::Failure[Integer].new(StandardError.new) # Try::Failure[Integer](@failure=#<StandardError: StandardError>)
-```
-
-### Unpacking
-
-Since `Try` can either contain success value in `Success` branch or error in `Failure` branch, there are specific accessors
-for success and failure values. In order to check whether a `Try` contains a successful value or value,
-predicates `#failure?` and `#success?` can be used:
-
-```ruby
-Try { 10 }.success? # true
-Try { 10 }.failure? # false
-
-Try { raise "Error" }.success? # false
-Try { raise "Error" }.failure? # true
-```
-
-In order to retrieve a successful value from `Try`, a method `#success` can be used. This method is only defined
-on `Mayak::Monads::Try::Success`, which is subtype of `Mayak::Monads::Try`. In order to invoke this method without getting an error from sorbet,
-instance of `Try` should be first coerced to checked and coerced to `Try::Success`. This can be done safely with pattern matching:
-
-```ruby
-try = Try { 10 }
-value = case try
-when Mayak::Monads::Try::Success
-  try.success
-else
-  nil
-end
-value # 10
-```
-
-If an instance of `Try` is a `Failure`, error can be retrieved via `#failure`:
-
-```ruby
-try = Try { raise "Error" }
-value = case try
-when Mayak::Monads::Try::Failure
-  try.failure
-when
-  nil
-end
-value # #<StandardError: Error>
-```
-
-Success and failure values can be retrieved via methods `#success_or` and `#failure_or` as well. These methods
-receives fallback values:
-
-```ruby
-Try { 10 }.success_or(0) # 10
-Try { 10 }.failure_or(StandardError.new("Error")) # #<StandardError: Error>
-
-Try { raise "Boom" }.success_or(0) # 0
-Try { raise "Boom" }.failure_or(StandardError.new("Error")) # #<StandardError: Boom>
-```
-
-### Methods
-
-#### `#map`
-
-The same as `fmap` in a dry-monads `Try`. Allows to modify the value with a block if it's present.
-
-```ruby
-sig { returns(Mayak::Monads::Try[Integer]) }
-def success
-  Mayak::Monads::Try::Success[Integer].new(10)
-end
-
-sig { returns(Mayak::Monads::Try[Integer]) }
-def failure
-  Mayak::Monads::Try::Failure[Integer].new(StandardError.new("Error"))
-end
-
-success.map { |a| a + 20 } # Success[Integer](value = 20)
-failure.map { |a| a + 20 } # Failure[Integer](error=#<StandardError: Error>)
-```
-
-#### `#flat_map`
-The same as `bind` in a dry-monads `Try`. Allows to modify the value with a block that returns another `Try`
-if it's a`Success`, otherwise returns `Failure`. If the block returns `Failure`, the whole computation returns `Failure`.
-
-```ruby
-sig { params(a: Integer, b: Integer).returns(Mayak::Monads::Try[Integer]) }
-def divide(a, b)
-  Try { a / b }
-end
-
-divide(20, 2).flat_map { |a| divide(a, 2) } # Try::Success[Integer](value = 5)
-divide(20, 2).flat_map { |a| divide(a, 0) } # Try::Failure[Integer](@failure=#<ZeroDivisionError: divided by 0>)
-divide(20, 0).flat_map { |a| divide(a, 2) } # Try::Failure[Integer](@failure=#<ZeroDivisionError: divided by 0>)
-```
-
-#### `#filter_or`
-
-Receives a block the returns a boolean value and checks the underlying value with the block when a monad is `Success`.
-Returns `Failure` with provided error if the block called on the value returns `false`, and returns `self` if the block returns `true`.
-Returns self if the original monad is `Failure`.
-
-```ruby
-error = StandardError.new("Provided error")
-divide(20, 2).filter_or(error) { |value| value > 5 } # Try::Success[Integer](value = 5)
-divide(20, 2).filter_or(error) { |value| value < 5 } # Try::Failure[Integer](@failure=#<StandardError: Provided error>)
-divide(20, 0).filter_or(error) { |value| value < 5 } # Try::Failure[Integer](@failure=#<ZeroDivisionError: divided by 0>)
-```
-
-#### `#success?`
-
-Returns true if a `Try` is a `Success` and false if it's a `Failure`.
-
-```ruby
-divide(20, 2).success? # true
-divide(20, 0).success? # false
-```
-
-#### `#failure?`
-
-Returns true if a `Try` is a `Failure` and false if it's a `Success`.
-
-```ruby
-divide(20, 2).failure? # false
-divide(20, 0).failure? # true
-```
-
-#### `#success_or`
-
-Unpack a `Try` and returns its success value if it's a `Success`, or returns provided fallback value if it's a `Failure`.
-
-```ruby
-divide(20, 2).value_or(0) # 10
-divide(20, 0).value_or(0) # 0
-```
-
-#### `#failure_or`
-
-Unpack a `Try` and returns its error if it's a `Failure`,
-or returns provided fallback error of `StandardError` subtype if it's a `Success`.
-
-```ruby
-divide(20, 2).failure_or(StandardError.new("Error")) # #<StandardError: Error>
-divide(20, 0).failure_or(StandardError.new("Error")) # #<ZeroDivisionError: divided by 0>
-```
-
-#### `#either`
-
-Receives two functions: one from an error to a result
-value (failure function), and another one from successful value to a result value (success function).
-If a `Try` is an instance of `Success`, applies success function to a success value,
-otherwise applies error function to an error. Note that both functions must have the same return type.
-
-```ruby
-divide(10, 2).either(
-  -> (error) { error.message },
-  -> (value) { value.to_s }
-) # 5
-
-divide(10, 0).either(
-  -> (error) { error.message },
-  -> (value) { value.to_s }
-) # Division by zero
-```
-
-#### `#tee`
-
-If a `Try` is an instance of `Success`, runs a block with a value of `Success` passed, and returns the monad itself
-unchanged. Doesn't do anything if the monad is an instance of `Failure`.
-
-```ruby
-divide(10, 2).tee { |a| puts a }
-# returns: Try::Success[Integer](value = 5)
-# console: 5
-
-divide(10, 0).tee { |a| puts a }
-# returns: Try::Failure[Integer](@failure=#<ZeroDivisionError: divided by 0>)
-```
-
-Can be useful to embed side-effects into chain of monad transformation:
-```ruby
-sig { params(a: Integer, b: Integer).returns(Try[String]) }
-def run(a, b)
-  divide(a, b)
-    .tee { |value| logger.info("#{a} / #{b} = #{value}") }
-    .map { |value| value * 100 }
-    .tee { |value| logger.info("Intermediate result = #{value}") }
-    .map(&:to_s)
-end
-```
-
-#### `#map_failure`
-
-Transforms an error with a block if a monad is `Failure`. Returns itself otherwise. Note that the passed block
-should return an instance of `StandardError`, or an instance of a subtype of the `StandardError`.
-
-```ruby
-divide(10, 0).map_failure { |error| CustomError.new(message) } # Try::Failure[Integer](@failure=#<CustomError: Division by zero>)
-divide(10, 2).map_failure { |error| CustomError.new(message) } # Try::Success[Integer](@value=5)
-```
-
-#### `#flat_map_failure`
-
-Transforms an error with a block that returns an instance of `Try` if a monad is `Failure`. Returns itself otherwise.
-Allows to recover from error with a computation, that can fail too.
-
-```ruby
-divide(10, 2).flat_map_failure { |_error|
-  Mayak::Monads::Try::Success[Integer].new(10)
-} # Try::Success[Integer](@value=5)
-
-divide(10, 2).flat_map_failure { |error|
-  Mayak::Monads::Try::Failure[Integer].new(StandardError.new(error.message))
-} # Try::Success[Integer](@value=5)
-
-divide(10, 0).flat_map_failure { |error|
-  Mayak::Monads::Try::Success[Integer].new(10)
-} # Try::Success[Integer](@value=2)
-
-divide(10, 0).flat_map_failure { |error|
-  Mayak::Monads::Try::Failure[Integer].new(CustomError.new(error.message))
-} # Try::Failure[Integer](@failure=#<CustomError: Division by zero>)
-```
-
-#### `#to_result`
-
-Converts a `Try` into a `Result`. If the `Try` is a `Try::Success`, returns `Result::Success` with a success value.
-If it's a `Failure`, returns `Result::Failre` with a an error value.
-
-```ruby
-divide(10, 2).to_result # Result::Success[StandardError, Integer](value = 5)
-divide(10, 0).to_result # Result::Failure[StandardError, Integer](error = #<ZeroDivisionError: divided by 0>)
-```
-
-#### `#to_task`
-
-Converts a value to task. If a `Try` is an instance of `Success`, it returns succeeded task, if it's a `Failure`,
-it returns failed task with an `Failure`'s error.
-
-```ruby
-task = Mayak::Concurrent::Task.execute { 100 }
-task.flat_map { |value| divide(value, 10).to_task }.await! # 10
-task.flat_map { |value| divide(value, 0).to_task }.await!  # StandardError: Divison by zero
-```
-
-#### `#to_maybe`
-
-Converts a `Try` value to `Maybe`. When the `Try` instance is a `Success`, returns `Maybe` containing successful value.
-When the `Try` is an instance of `Failure`, returns `None`. Note that during the transformation error is lost.
-
-```ruby
-divide(10, 2).to_maybe # Some[Integer](value = 5)
-divide(10, 0).to_maybe # None[Integer]
-```
-
-#### `#as`
-
-Substitutes successful value in `Try::Success` with a new value, if the monad is instance of `Try::Failure`, returns
-the monad unchanged.
-
-```ruby
-divide(10, 2).as("Success")# Try::Success[String](@value="Success")
-divide(10, 0).as("Success") # Try::Failure[String](@failure=#<ZeroDivisionError: Division by zero>)
-```
-
-#### `#failure_as`
-
-Substitutes an error `Try::Failure` with a new error, if the monad is instance of `Try::Success`, returns
-the monad unchanged.
-
-```ruby
-divide(10, 2).failure_as(StandardError.new("Error")) # Try::Success[Integer](@value=5)
-divide(10, 0).failure_as(StandardError.new("Error")) # Try::Failure[Integer](@failure=#<StandardError: Error>)
-```
-
-#### `#recover`
-
-Converts `Failure` into a `Success` with a provided value. If the monad is an instance of `Success`, returns itself.
-Basically, recovers from an error with a successful value.
-
-```ruby
-divide(10, 2).recover(0) # Try::Success[Integer](value = 5)
-divide(10, 0).recover(0) # Try::Success[Integer](value = 5)
-```
-
-#### `#recover_on`
-
-Converts `Failure` into a `Success` with a provided value if an error is an instance of a subtype of provided class. If the monad is an instance of `Success`, returns itself.
-Allows to recover from specific errors.
-
-```ruby
-class CustomError1 < StandardError
-end
-
-class CustomError2 < StandardError
-end
-
-failure1 = Mayak::Monads::Try::Failure[String].new(CustomError1.new("Error1"))
-failure2 = Mayak::Monads::Try::Failure[String].new(CustomError2.new("Error2"))
-
-failure1.recover_on(CustomError1) { |error| error.message } # Try::Success[String](@value="Error1")
-failure2.recover_on(CustomError1) { |error| error.message } # Try::Failure[String](@failure=#<CustomError2: Error2>)
-```
-
-Note, that an error passed in the block is not down casted. So from sorbet perspective it still will be
-a `StandardError`.
-
-```ruby
-failure1.recover_on(CustomError1) { |error|
-  T.reveal_type(error)
-  "Error"
-}
-# Revealed type: StandardError
-```
-
-#### `#recover_with`
-
-Alias for `#flat_map_failure`.
-
-#### `.sequence`
-`Try.sequence` takes an array of `Try`s and transform it into a `Try` of an array.
-If all elements of the array is `Success`, then the method returns `Try::Sucess` containing array of values,
-otherwise the method returns `Try::Failure` containing first error.
-
-```ruby
-include Mayak::Monads
-
-values = [
-  Try::Success[Integer].new(1),
-  Try::Success[Integer].new(2),
-  Try::Success[Integer].new(3)
-]
-Try.sequence(values) # Try::Success[T::Array[Integer]](@value=[1, 2, 3])
-
-values = [
-  Try::Success[Integer].new(1),
-  Try::Failure[Integer].new(ArgumentError.new("Error1")),
-  Try::Failure[Integer].new(StandardError.new("Error2"))
-]
-Try.sequence(values) # Try::Failure[Integer](@failure=#<ArgumentError: Error1>)
-```
-
-#### `.check`
-
-Receives a value, an error, and block returning a boolean value. If the block returns true,
-the method returns the value wrapped in `Try::Success`, otherwise it returns `Try::Failure` containing the error:
-
-```ruby
-error = StandardError.new("Error")
-Try.check(10, error) { 20 > 10 } # Try::Success[Integer](@failure=10)
-Try.check(20, error) { 10 > 20 } # Try::Failure[Integer](@failure=#<StandardError: Error>)
-```
-
-#### `.guard`
-
-Receives a block returning a boolean value, and an error. If the block returns true,
-the method returns `Try::Success` containing nil, otherwise it returns `Try::Failure` containing an error:
-
-```ruby
-error = StandardError.new("Error")
-Maybe.guard(error) { 20 > 10 } # Try::Success[NilClass](@failure=nil)
-Maybe.guard(error) { 10 > 20 } # Try::Failure[NilClass](@failure=#<StandardError: Error>)
-```
-
-This method may be useful in do-notations when you need need to check some invariant and perform
-an early return if it doesn't hold.
-
-### Do-notation
-
-`Try` monad supports `do-notation` just like `Maybe` monad. Check do-notation chapter of [Maybe](#maybe) for motivation.
-Do-notation for `Try` is quite similar for `Maybe`'s do-notation, albeit there are some differences in syntax and semantics.
-Do-notation scope is created via method `for_try`, a monad is unwrapped via `do_try!`.
-
-```ruby
-result = for_try {
-  first  = do_try! Try::Success[Integer].new(10)
-  second = do_try! Try::Success[Integer].new(20)
-  first + second
-}
-result # Try::Success[Integer](@value=30)
-```
-
-When an instance of `Try::Failure` is unwrapped via `do_try!` the whole computation returns this monad.
-
-```ruby
-result = for_try {
-  first  = do_try! Try::Success[Integer].new(10)
-  second = do_try! Try::Failure[Integer].new(StandardError.new("Error"))
-  third  = do_try! Try::Success[Integer].new(20)
-  first + second + third
-}
-result # Try::Failure[Integer](@failure=#<StandardError: Error>)
-```
-
-Methods `check_try!` and `guard_try!` to perform early returns.
-
-```ruby
-sig { params(a: Integer, b: Integer).returns(Try[Float]) }
-def compute(a, b)
-  argument_error = ArgumentError.new("Argument is less than zero")
-  for_try {
-    guard_try! (argument_error) { a < 0 || b < 0 }
-    first  = do_try! Try { a / b }
-    second = do_try! Try { Math.log(a, b) }
-    result = first + second
-    check_try!(result, StandardError.new("Number is too big")) { result < 100 }
-  }
-end
-```
-
-Do-notation for `Try` is fully typed as well.
-
-```ruby
-for_try {
-  value = do_try! Try { 10 }
-  T.reveal_type(value)
-  value
-}
-# > Revealed type: Integer
-
-result = for_try {
-  value = do_try! Try { 10 }
-  value
-}
-T.reveal_type(result)
-# > Revealed type: Integer
-```
-
-## Result
-
-`Result` monad represents result of a computation that can succeed with an arbitrary value, or fail with an arbitrary error.
-As `Try`, `Result` has two subtypes: `Failure` which contains an error and represents failure case, and `Success`, which contains
-a success value. The difference between `Result` and `Try`, is that `Result` has arbitrary error type, while `Try` has it fixed to `StandardError`.
-
-
-### Initialization
-
-The primary way to create an instance of `Try` is to use constructor method `#Try` from `Mayak::Monads::Try::Mixin`.
-This method receives a block that may raise exceptions. If an exception has been raised inside the block,
-the method will return instance of `Try::Failure` containing an error. Otherwise the method will return result of the block
-wrapped into `Try::Success`
-
-`Result` can be created via primary constructors of `Result::Success` and `Result::Failure`:
-
-```ruby
-include Mayak::Monads
-
-Result::Success[String, Integer].new(10)
-Result::Failure[String, Integer].new("Error")
-```
-
-### Unpacking
-
-Accessing values of `Result` performed in the same as for `Try`.
-
-```ruby
-success  = Result::Success[String, Integer].new(10)
-failure = Result::Failure[String, Integer].new("Error")
-success.success? # true
-success.failure? # false
-
-failure.success? # false
-failure.failure? # true
-```
-
-Successful and failure values can be accessed via `#success` and `#failure` values. These methods
-are defined on `Result::Success`, and `Result::Failure` subtypes respectively, so in order to access
-them value of type `Result` should be downcasted first:
-
-```ruby
-result = Result::Success[String, Integer].new(10)
-value = case result
-when Result::Success
-  try.success
-else
-  nil
-end
-value # 10
-
-result = Result::Failure[String, Integer].new("Error")
-value = case result
-when Result::Failure
-  result.failure
-when
-  nil
-end
-value # "Error"
-```
-
-Success and failure values can be retrieved via methods `#success_or` and `#failure_or` as well. These methods
-receives fallback values:
-
-```ruby
-Result::Success[String, Integer].new(10).success_or(0) # 10
-Result::Success[String, Integer].new(10).failure_or("Error") # "Error"
-
-Result::Failure[String, Integer].new("Error").success_or(0) # 0
-Result::Failure[String, Integer].new("Error").failure_or("Another Error") # "Error"
-```
-
-### Methods
-
-#### `#map`
-
-The same as `fmap` in a dry-monads `Result`. Allows to modify the value with a block if it's present.
-
-```ruby
-sig { returns(Result[String, Integer]) }
-def success
-  Result::Success[String, Integer].new(10)
-end
-
-sig { returns(Result[String, Integer]) }
-def failure
-  Result::Failure[String, Integer].new("Error")
-end
-
-success.map { |a| a + 20 } # Result::Success[Integer](value = 20)
-failure.map { |a| a + 20 } # Result::Failure[Integer](error=#<StandardError: Error>)
-```
-
-#### `#flat_map`
-
-The same as `bind` in a dry-monads `Result`. Allows to modify the value with a block that returns another `Result`
-if it's a `Result::Success`, otherwise returns `Result::Failure`. If the block returns `Result::Failure`, the whole computation returns `Result::Failure`.
-
-```ruby
-sig { params(a: Integer, b: Integer).returns(Mayak::Monads::Result[String, Integer]) }
-def divide(a, b)
-  if a == 0
-    Result::Failure[String, Integer].new("Division by zero")
-  else
-    Result::Success[String, Integer].new(a / b)
-  end
-end
-
-divide(20, 2).flat_map { |a| divide(a, 2) } # Result::Success[String, Integer](value = 5)
-divide(20, 2).flat_map { |a| divide(a, 0) } # Result::Failure[String, Integer](@failure="Division by zero")
-divide(20, 0).flat_map { |a| divide(a, 2) } # Result::Failure[String, Integer](@failure="Division by zero")
-```
-
-#### `#filter_or`
-
-Receives a block the returns a boolean value and checks the underlying value with the block when a monad is `Result::Success`.
-Returns `Result::Failure` with provided error if the block called on the value returns `false`, and returns `self` if the block returns `true`.
-Returns self if the original monad is `Result::Failure`.
-
-```ruby
-divide(10, 2).filter_or("Above 5") { |value| value <= 5 } # Result::Success[String, Integer](value = 5)
-divide(20, 2).filter_or("Above 5") { |value| value <= 5 } # Result::Failure[String, Integer](@failure="Above 5")
-divide(10, 0).filter_or("Above 5") { |value| value <= 5 } # Result::Failure[String, Integer](@failure="Division by zero")
-```
-
-#### `#success?`
-
-Returns true if a `Result` is a `Result::Success` and false if it's a `Result::Failure`.
-
-```ruby
-divide(20, 2).success? # true
-divide(20, 0).success? # false
-```
-
-#### `#failure?`
-
-Returns true if a `Result` is a `Result::Failure` and false if it's a `Result::Success`.
-
-```ruby
-divide(20, 2).failure? # false
-divide(20, 0).failure? # true
-```
-
-#### `#success_or`
-
-Unpack a `Result` and returns its success value if it's a `Result::Success`, or returns provided fallback value if it's a `Result::Failure`.
-
-```ruby
-divide(20, 2).value_or(0) # 10
-divide(20, 0).value_or(0) # 0
-```
-
-#### `#failure_or`
-
-Unpack a `Result` and returns its error if it's a `Result::Failure`,
-or returns provided fallback error of `StandardError` subtype if it's a `Success`.
-
-```ruby
-divide(20, 2).failure_or("Error") # "Error"
-divide(20, 0).failure_or("Error") # "Division by zero"
-```
-
-#### `#flip`
-
-Flips failure and success channels, converting `Result[A, B]` into `Result[B, A]`.
-Basically, transforms `Success` into `Failure` and vice versa.
-
-
-```ruby
-divide(10, 2).flip # Result::Failure[Integer, String](value = 5)
-divide(10, 0).flip # Result::Success[Integer, String](value = "Division by zero")
-```
-
-#### `#either`
-
-Receives two functions: one from an error to a result
-value (failure function), and another one from successful value to a result value (success function).
-If a `Result` is an instance of `Result::Success`, applies success function to a success value,
-otherwise applies error function to an error. Note that both functions must have the same return type.
-
-```ruby
-divide(10, 2).either(
-  -> (error) { "Error occurred: `#{error}`" },
-  -> (value) { value.to_s }
-) # 5
-
-divide(10, 0).either(
-  -> (error) { "Error occurred: #{error}" },
-  -> (value) { value.to_s }
-) # Error occurred: `Division by zero`
-```
-
-#### `#tee`
-
-If a `Result` is an instance of `Result::Success`, runs a block with a value of `Result::Success` passed, and returns the monad itself
-unchanged. Doesn't do anything if the monad is an instance of `Result::Failure`.
-
-```ruby
-divide(10, 2).tee { |a| puts a }
-# returns: Result::Success[String, Integer](value=5)
-# console: 5
-
-divide(10, 0).tee { |a| puts a }
-# returns: Result::Failure[String, Integer](@failure="Division by zero")
-```
-
-#### `#map_failure`
-
-Transforms an error with a block if a monad is `Failure`. Returns itself otherwise. Note that the passed block
-should return an instance of `StandardError`, or an instance of a subtype of the `StandardError`.
-
-```ruby
-divide(10, 0).map_failure { |error| "Error occurred: `#{error}`" } # Result::Failure[String, Integer](@failure="Error occurred: `Division by zero`")
-divide(10, 2).map_failure { |error| "Error occurred: `#{error}`" } # Result::Success[String, Integer](@value=5)
-```
-
-#### `#flat_map_failure`
-
-Transforms an error with a block that returns an instance of `Result` if a monad is `Result::Failure`. Returns itself otherwise.
-Allows to recover from error with a computation, that can fail too.
-
-```ruby
-divide(10, 2).flat_map_failure { |_error|
-  Result::Success[String, Integer].new(0)
-} # Result::Success[String, Integer](@value=5)
-
-divide(10, 2).flat_map_failure { |error|
-  Result::Failure[String, Integer].new("Error")
-} # Result::Success[String, Integer](@value=2)
-
-divide(10, 0).flat_map_failure { |error|
-  Result::Success[String, Integer].new(0)
-} # Result::Success[String, Integer](@value=0)
-
-divide(10, 0).flat_map_failure { |error|
-  Result::Success[String, Integer].new("Error")
-} # Result::Failure[String, Integer](@failure="Error")
-```
-
-#### `#to_task`
-
-Converts a value to task. Receives a block that converts an error into an instance of `StandardError`.
-If a `Result` is an instance of `Result::Success`, it returns succeeded task.
-If it's a `Result::Failure`, it returns failed task with an `Failure`'s error returned by the block.
-
-```ruby
-task = Mayak::Concurrent::Task.execute { 100 }
-
-task.flat_map { |value|
-  divide(value, 10).to_task { |error| StandardError.new(error) }
-}.await! # 10
-
-task.flat_map { |value|
-  divide(value, 0).to_task { |error| StandardError.new(error) }
-}.await!  # StandardError: Divison by zero
-```
-
-#### `#to_try`
-
-Converts a `Result` into a `Try`. Receives a block that converts an error into an instance of `StandardError`.
-If the `Result` is a `Result::Success`, returns `Try::Success` with a success value.
-If it's a `Result::Failure`, returns `Try::Failre` with a an error value returned by the block.
-
-```ruby
-divide(10, 2).to_result { |error| StandardError.new(error) } # Try::Success[Integer](value = 5)
-divide(10, 0).to_result { |error| StandardError.new(error) } # Try::Failure[Integer](error = #<ZeroDivisionError: divided by 0>)
-```
-
-#### `#to_maybe`
-
-Converts a `Result` value to `Maybe`. When the `Result` instance is a `Result::Success`, returns `Maybe` containing successful value.
-When the `Result` is an instance of `Result::Failure`, returns `None`. Note that during the transformation error is lost.
-
-```ruby
-divide(10, 2).to_maybe # Some[Integer](value = 5)
-divide(10, 0).to_maybe # None[Integer]
-```
-
-#### `#as`
-
-Substitutes successful value in `Result::Success` with a new value, if the monad is instance of `Result::Failure`, returns
-the monad unchanged.
-
-```ruby
-divide(10, 2).as("Success") # Result::Success[String, String](@value="Success")
-divide(10, 0).as("Success") # Result::Failure[String, String](@failure="Division by zero")
-```
-
-#### `#failure_as`
-
-Substitutes an error `Result::Failure` with a new error, if the monad is instance of `Try::Success`, returns
-the monad unchanged.
-
-```ruby
-divide(10, 2).failure_as(0) # Result::Success[Integer, Integer](@value=5)
-divide(10, 0).failure_as(0) # Result::Failure[Integer, Integer](@failure=0)
-```
-
-#### `#recover`
-
-Converts `Result::Failure` into a `Result::Success` with a provided value. If the monad is an instance of `Result::Success`, returns itself.
-Basically, recovers from an error with a successful value.
-
-```ruby
-divide(10, 2).recover(0) # Result::Success[String, Integer](value = 5)
-divide(10, 0).recover(0) # Result::Success[Integer](value = 5)
-```
-
-#### `#recover_with`
-
-Receives a block that converts an error into successful value, and converts `Failure` into a `Success` with the value.
-If the monad is an instance of `Success`, returns itself.Basically, recovers from an error with a successful value.
-
-```ruby
-divide(10, 2).recover_with { |error|
-  if error == "Division by zero"
-    0
-  else
-    -1
-  end
-} # Result::Success[String, Integer](value = 5)
-divide(10, 2).recover_with { |error|
-  if error == "Division by zero"
-    0
-  else
-    -1
-  end
-} # Result::Success[Integer](value = 0)
-```
-
-#### `#recover_with_result`
-
-Alias for `#flat_map_failure`.
-
-#### `.sequence`
-`Result.sequence` takes an array of `Result`s and transform it into a `Result` of an array.
-If all elements of the array is `Result::Success`, then the method returns `Result::Sucess` containing array of values,
-otherwise the method returns `Result::Failure` containing first error.
-
-```ruby
-include Mayak::Monads
-
-values = [
-  Result::Success[String, Integer].new(1),
-  Result::Success[String, Integer].new(2),
-  Result::Success[String, Integer].new(3)
-]
-Result.sequence(values) # Result::Success[String, T::Array[Integer]](@value=[1, 2, 3])
-
-values = [
-  Result::Success[String, Integer].new(1),
-  Result::Failure[String, Integer].new("Error1"),
-  Result::Failure[String, Integer].new("Error2")
-]
-Result.sequence(values) # Result::Failure[String, Integer](@failure="Error")
-```
-
-### Do-notation
-
-`Result` monad does not supports do-notation. The fact that `Result` has two type-parameters makes
-it not possible to implement type-safe do-notation in the same fashion as it done for `Maybe` and `Try`.