dry-monads 1.3.2 → 1.4.0

data/docsite/source/case-equality.html.md

@@ -1,42 +0,0 @@
----
-title: Case equality
-layout: gem-single
-name: dry-monads
----
-
-### Case equality
-
-Monads allow to use default ruby `case` operator for matching result:
-
-```ruby
-case value
-when Some(1), Some(2) then :one_or_two
-when Some(3..5) then :three_to_five
-else
-  :something_else
-end
-```
-
-You can use specific `Failure` options too:
-
-```ruby
-case value
-when Success then [:ok, value.value!]
-when Failure(TimeoutError) then [:timeout]
-when Failure(ConnectionClosed) then [:net_error]
-when Failure then [:generic_error]
-else
-  raise "Unhandled case"
-end
-```
-
-#### Nested structures
-
-```ruby
-case value
-when Success(None()) then :nothing
-when Success(Some { |x| x > 10 }) then :something
-when Success(Some) then :something_else
-when Failure then :error
-end
-```

data/docsite/source/do-notation.html.md

@@ -1,207 +0,0 @@
----
-title: Do notation
-layout: gem-single
-name: dry-monads
----
-
-Composing several monadic values can become tedious because you need to pass around unwrapped values in lambdas (aka blocks). Haskell was one of the first languages faced this problem. To work around it Haskell has a special syntax for combining monadic operations called the "do notation". If you're familiar with Scala it has `for`-comprehensions for a similar purpose. It is not possible to implement `do` in Ruby but it is possible to emulate it to some extent, i.e. achieve comparable usefulness.
-
-What `Do` does is passing an unwrapping block to certain methods. The block tries to extract the underlying value from a monadic object and either short-circuits the execution (in case of a failure) or returns the unwrapped value back.
-
-See the following example written using `bind` and `fmap`:
-
-```ruby
-require 'dry/monads'
-
-class CreateAccount
-  include Dry::Monads[:result]
-
-  def call(params)
-    validate(params).bind { |values|
-      create_account(values[:account]).bind { |account|
-        create_owner(account, values[:owner]).fmap { |owner|
-          [account, owner]
-        }
-      }
-    }
-  end
-
-  def validate(params)
-    # returns Success(values) or Failure(:invalid_data)
-  end
-
-  def create_account(account_values)
-    # returns Success(account) or Failure(:account_not_created)
-  end
-
-  def create_owner(account, owner_values)
-    # returns Success(owner) or Failure(:owner_not_created)
-  end
-end
-```
-
-The more monadic steps you need to combine the harder it becomes, not to mention how difficult it can be to refactor code written in such way.
-
-Embrace `Do`:
-
-```ruby
-require 'dry/monads'
-require 'dry/monads/do'
-
-class CreateAccount
-  include Dry::Monads[:result]
-  include Dry::Monads::Do.for(:call)
-
-  def call(params)
-    values = yield validate(params)
-    account = yield create_account(values[:account])
-    owner = yield create_owner(account, values[:owner])
-
-    Success([account, owner])
-  end
-
-  def validate(params)
-    # returns Success(values) or Failure(:invalid_data)
-  end
-
-  def create_account(account_values)
-    # returns Success(account) or Failure(:account_not_created)
-  end
-
-  def create_owner(account, owner_values)
-    # returns Success(owner) or Failure(:owner_not_created)
-  end
-end
-```
-
-Both snippets do the same thing yet the second one is a lot easier to deal with. All what `Do` does here is prepending `CreateAccount` with a module which passes a block to `CreateAccount#call`. That simple.
-
-### Transaction safety
-
-Under the hood, `Do` uses exceptions to halt unsuccessful operations, this can be slower if you are dealing with unsuccessful paths a lot, but usually, this is not an issue. Check out [this article](https://www.morozov.is/2018/05/27/do-notation-ruby.html) for actual benchmarks.
-
-One particular reason to use exceptions is the ability to make code transaction-friendly. In the example above, this piece of code is not atomic:
-
-```ruby
-account = yield create_account(values[:account])
-owner = yield create_owner(account, values[:owner])
-
-Success[account, owner]
-```
-
-What if `create_account` succeeds and `create_owner` fails? This will leave your database in an inconsistent state. Let's wrap it with a transaction block:
-
-```ruby
-repo.transaction do
-  account = yield create_account(values[:account])
-  owner = yield create_owner(account, values[:owner])
-
-  Success[account, owner]
-end
-```
-
-Since `yield` internally uses exceptions to control the flow, the exception will be detected by the `transaction` call and the whole operation will be rolled back. No more garbage in your database, yay!
-
-### Limitations
-
-`Do` only works with single-value monads, i.e. most of them. At the moment, there is no way to make it work with `List`, though.
-
-### Adding batteries
-
-The `Do::All` module takes one step ahead, it tracks all new methods defined in the class and passes a block to every one of them. However, if you pass a block yourself then it takes precedence. This way, in most cases you can use `Do::All` instead of listing methods with `Do.for(...)`:
-
-```ruby
-require 'dry/monads'
-
-class CreateAccount
-  # This will include Do::All by default
-  include Dry::Monads[:result, :do]
-
-  def call(account_params, owner_params)
-    repo.transaction do
-      account = yield create_account(account_params)
-      owner = yield create_owner(account, owner_params)
-
-      Success[account, owner]
-    end
-  end
-
-  def create_account(params)
-    values = yield validate_account(params)
-    account = repo.create_account(values)
-
-    Success(account)
-  end
-
-  def create_owner(account, params)
-    values = yield validate_owner(params)
-    owner = repo.create_owner(account, values)
-
-    Success(owner)
-  end
-
-  def validate_account(params)
-    # returns Success/Failure
-  end
-
-  def validate_owner(params)
-    # returns Success/Failure
-  end
-end
-```
-
-### Using `Do` methods in other contexts
-
-You can use methods from the `Do` module directly (starting with 1.3):
-
-```ruby
-require 'dry/monads/do'
-require 'dry/monads/result'
-
-# some random place in your code
-Dry::Monads.Do.() do
-  user = Dry::Monads::Do.bind create_user
-  account = Dry::Monads::Do.bind create_account(user)
-
-  Dry::Monads::Success[user, account]
-end
-```
-
-Or you can use `extend`:
-
-```ruby
-require 'dry/monads'
-
-class VeryComplexAndUglyCode
-  extend Dry::Monads::Do::Mixin
-  extend Dry::Monads[:result]
-
-  def self.create_something(result_value)
-    call do
-      extracted = bind result_value
-      processed = bind process(extracted)
-
-      Success(processed)
-    end
-  end
-end
-```
-
-`Do::All` also works with class methods:
-
-```ruby
-require 'dry/monads'
-
-class SomeClassLevelLogic
-  extend Dry::Monads[:result, :do]
-
-  def self.call
-    x = yield Success(5)
-    y = yield Success(20)
-
-    Success(x * y)
-  end
-end
-
-SomeClassLevelLogic.() # => Success(100)
-```

data/docsite/source/getting-started.html.md

@@ -1,142 +0,0 @@
----
-title: Getting started
-layout: gem-single
-name: dry-monads
----
-
-### Installation
-
-Add this line to your Gemfile
-
-```ruby
-gem 'dry-monads'
-```
-
-Then run
-
-```
-$ bundle
-```
-
-### Usage
-
-Every monad has corresponding value constructors. For example, the `Maybe` monad has two of them: `Some(...)` and `None()`. It also has the `Maybe(...)` method. All three methods start with a capital letter similarly to built-in Ruby methods like `Kernel#Array(...)` and `Kernel#Hash(...)`. Value constructors are not available globally, you need to add them with a mixin.
-
-To add the `Maybe` constructors add `Dry::Monads[:maybe]` to your class:
-
-```ruby
-require 'dry/monads'
-
-class CreateUser
-  # this line loads the Maybe monad and adds
-  # Some(...), None(), and Maybe(...) to CreateUser
-  include Dry::Monads[:maybe]
-
-  def call(params)
-    # ...
-    if valid?(params)
-      None()
-    else
-      Some(create_user(params))
-    end
-  end
-end
-```
-
-Example in the docs may use `extend Dry::Monads[...]` for brevity but you normally want to use `include` in production code.
-
-### Including multiple monads
-
-```ruby
-require 'dry/monads'
-
-class CreateUser
-  # Adds Maybe and Result. The order doesn't matter
-  include Dry::Monads[:maybe, :result]
-end
-```
-
-### Using with do notation
-
-A very common case is using the [Result](docs::result) monad with [do notation](docs::do-notation):
-
-```ruby
-require 'dry/monads'
-
-class ResultCalculator
-  include Dry::Monads[:result, :do]
-
-  def calculate(input)
-    value = Integer(input)
-
-    value = yield add_3(value)
-    value = yield mult_2(value)
-
-    Success(value)
-  end
-
-  def add_3(value)
-    if value > 1
-      Success(value + 3)
-    else
-      Failure("value was less than 1")
-    end
-  end
-
-  def mult_2(value)
-    if value % 2 == 0
-      Success(value * 2)
-    else
-      Failure("value was not even")
-    end
-  end
-end
-
-
-c = ResultCalculator.new
-c.calculate(3) # => Success(12)
-c.calculate(0) # => Failure("value was less than 1")
-c.calculate(2) # => Failure("value was not even")
-```
-
-### Constructing array values
-
-Some constructors have shortcuts for wrapping arrays:
-
-```ruby
-require 'dry/monads'
-
-class CreateUser
-  include Dry::Monads[:result]
-
-  def call(params)
-    # ...
-    # Same as Failure([:user_exists, params: params])
-    Failure[:user_exists, params: params]
-  end
-end
-```
-
-### Interaction between monads and constructors availability
-
-Some values can be converted to others or they can have methods that use other monads. By default, dry-monads doesn't load all monads so you may have troubles like this:
-
-```ruby
-extend Dry::Monads[:result]
-
-Success(:foo).to_maybe # RuntimeError: Load Maybe first with require 'dry/monads/maybe'
-```
-
-To work around you may either load `dry/monads/maybe` add `maybe` to the mixin:
-
-```ruby
-extend Dry::Monads[:result, :maybe]
-
-Success(:foo).to_maybe # => Some(:foo)
-```
-
-For the same reason `Dry::Monads.Some(...)`, `Dry::Monads.Success(...)`, and some other constructors are not available until you explicitly load the monads with `require 'dry/monads/%{monad_name}'`.
-
-### Loading everything
-
-Just `require 'dry/monads/all'`

data/docsite/source/index.html.md

@@ -1,179 +0,0 @@
----
-title: Introduction
-description: Common monads for Ruby
-layout: gem-single
-type: gem
-name: dry-monads
-sections:
-  - getting-started
-  - maybe
-  - result
-  - do-notation
-  - try
-  - list
-  - task
-  - validated
-  - case-equality
-  - tracing-failures
-  - pattern-matching
-  - unit
----
-
-dry-monads is a set of common monads for Ruby. Monads provide an elegant way of handling errors, exceptions and chaining functions so that the code is much more understandable and has all the error handling, without all the `if`s and `else`s. The gem was inspired by the [Kleisli](https://github.com/txus/kleisli) gem.
-
-What is a monad, anyway? Simply, [a monoid in the category of endofunctors](https://stackoverflow.com/questions/3870088/a-monad-is-just-a-monoid-in-the-category-of-endofunctors-whats-the-proble%E2%85%BF). The term comes from category theory and some believe monads are tough to understand or explain. It's hard to say why people think so because you certainly don't need to know category theory for using them, just like you don't need it for, say, using functions.
-
-Moreover, the best way to develop intuition about monads is looking at examples rather than learning theories.
-
-## How to use it?
-
-Let's say you have code like this
-
-```ruby
-user = User.find_by(id: params[:id])
-
-if user
-  address = user.address
-end
-
-if address
-  city = address.city
-end
-
-if city
-  state = city.state
-end
-
-if state
-  state_name = state.name
-end
-
-user_state = state_name || "No state"
-```
-
-Writing code in this style is tedious and error-prone. There were created several "cutting-corners" means to work around this issue. The first is ActiveSupport's `.try` which is a plain global monkey patch on `NilClass` and `Object`. Another solution is using the Safe Navigation Operator `&.` introduced in Ruby 2.3 which is a bit better because this is a language feature rather than an opinionated runtime environment pollution. However, some people think these solutions are hacks and the problem reveals a missing abstraction. What kind of abstraction?
-
-When all objects from the chain of objects are there we could have this instead:
-
-```ruby
-state_name = User.find_by(id: params[:id]).address.city.state.name
-user_state = state_name || "No state"
-```
-
-By using the `Maybe` monad you can preserve the structure of this code at a cost of introducing a notion of `nil`-able result:
-
-```ruby
-state_name = Maybe(User.find_by(id: params[:id])).maybe(&:address).maybe(&:city).maybe(&:state).maybe(&:name)
-user_state = state_name.value_or("No state")
-```
-
-`Maybe(...)` wraps the first value and returns a monadic value which either can be a `Some(user)` or `None` if `user` is `nil`. `maybe(&:address)` transforms `Some(user)` to `Some(address)` but leaves `None` intact. To get the final value you can use `value_or` which is a safe way to unwrap a `nil`-able value. In other words, once you've used `Maybe` you _cannot_ hit `nil` with a missing method. This is remarkable because even `&.` doesn't save you from omitting `|| "No state"` at the end of the computation. Basically, that's what they call "Type Safety".
-
-A more expanded example is based on _composing_ different monadic values. Suppose, we have a user and address, both can be `nil`, and we want to associate the address with the user:
-
-```ruby
-user = User.find_by(id: params[:user_id])
-address = Address.find_by(id: params[:address_id])
-
-if user && address
-  user.update(address_id: address.id)
-end
-```
-
-Again, this implies direct work with `nil`-able values which may end up with errors. A monad-way would be using another method, `bind`:
-
-```ruby
-maybe_user = Maybe(User.find_by(id: params[:user_id]))
-
-maybe_user.bind do |user|
-  maybe_address = Maybe(Address.find_by(id: params[:address_id]))
-
-  maybe_address.bind do |address|
-    user.update(address_id: address.id)
-  end
-end
-```
-
-One can say this code is opaque compared to the previous example but keep in mind that in _real code_ it often happens to call methods returning `Maybe` values. In this case, it might look like this:
-
-```ruby
-find_user(params[:user_id]).bind do |user|
-  find_address(params[:address_id]).bind do |address|
-    Some(user.update(address_id: address.id))
-  end
-end
-```
-
-Finally, since 1.0, dry-monads has support for [`do` notation](docs::do-notation) which simplifies this code even more, making it almost regular yet `nil`-safe:
-
-```ruby
-user = yield find_user(params[:user_id])
-address = yield find_address(params[:address_id])
-
-Some(user.update(address_id: address.id))
-```
-
-Another widely spread monad is `Result` (also known as `Either`) that serves a similar purpose. A notable downside of `Maybe` is plain `None` which carries no information about where this value was produced. `Result` solves exactly this problem by having two constructors for `Success` and `Failure` cases:
-
-```ruby
-def find_user(user_id)
-  user = User.find_by(id: user_id)
-
-  if user
-    Success(user)
-  else
-    Failure(:user_not_found)
-  end
-end
-
-def find_address(address_id)
-  address = Address.find_by(id: address_id)
-
-  if address
-    Success(address)
-  else
-    Failure(:address_not_found)
-  end
-end
-```
-
-You can compose `find_user` and `find_address` with `bind`:
-
-```ruby
-find_user(params[:user_id]).bind do |user|
-  find_address(params[:address_id]).bind |address|
-    Success(user.update(address_id: address.id))
-  end
-end
-```
-
-The inner block can be simplified with `fmap`:
-
-```ruby
-find_user(params[:user_id]).bind do |user|
-  find_address(params[:address_id]).fmap |address|
-    user.update(address_id: address.id)
-  end
-end
-```
-
-Or, again, the same code with `do`:
-
-```ruby
-user = yield find_user(params[:user_id])
-address = yield find_address(params[:address_id])
-
-Success(user.update(address_id: address.id))
-```
-
-The result of this piece of code can be one of `Success(user)`, `Failure(:user_not_found)`, or `Failure(:address_not_found)`. This style of programming called "Railway Oriented Programming" and can check out [dry-transaction](/gems/dry-transaction) and watch a [nice video](https://fsharpforfunandprofit.com/rop/) on the subject. Also, see [dry-matcher](/gems/dry-matcher) for an example of how to use monads for controlling the flow of code with a result.
-
-## A word of warning
-
-Before `do` came around here was a warning about over-using monads, turned out with `do` notation code does not differ much from regular Ruby code. Just don't wrap everything with `Maybe`, come up with conventions.
-
-If you're interested in functional programming in general, consider learning other languages such as Haskell, Scala, OCaml, this will make you a better programmer no matter what programming language you use on a daily basis. And if not earlier then maybe after that dry-monads will become another instrument in your Ruby toolbox :)
-
-## Credits
-
-dry-monads is inspired by Josep M. Bach’s [Kleisli](https://github.com/txus/kleisli) gem and its usage by [dry-transaction](/gems/dry-transaction/) and [dry-types](/gems/dry-types/).