dry-monads 1.3.1 → 1.3.2

data/docsite/source/index.html.md

@@ -0,0 +1,179 @@
+---
+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/).

data/docsite/source/list.html.md

@@ -0,0 +1,87 @@
+---
+title: List
+layout: gem-single
+name: dry-monads
+---
+
+### `bind`
+
+Lifts a block/proc and runs it against each member of the list. The block must return a value coercible to a list. As in other monads if no block given the first argument will be treated as callable and used instead.
+
+```ruby
+require 'dry/monads/list'
+
+M = Dry::Monads
+
+M::List[1, 2].bind { |x| [x + 1] } # => List[2, 3]
+M::List[1, 2].bind(-> x { [x, x + 1] }) # => List[1, 2, 2, 3]
+
+M::List[1, nil].bind { |x| [x + 1] } # => error
+```
+
+### `fmap`
+
+Maps a block over the list. Acts as `Array#map`. As in other monads, if no block given the first argument will be treated as callable and used instead.
+
+```ruby
+require 'dry/monads/list'
+
+M = Dry::Monads
+
+M::List[1, 2].fmap { |x| x + 1 } # => List[2, 3]
+```
+
+### `value`
+
+You always can unwrap the result by calling `value`.
+
+```ruby
+require 'dry/monads/list'
+
+M = Dry::Monads
+
+M::List[1, 2].value # => [1, 2]
+```
+
+### Concatenation
+
+```ruby
+require 'dry/monads/list'
+
+M = Dry::Monads
+
+M::List[1, 2] + M::List[3, 4] # => List[1, 2, 3, 4]
+```
+
+### `head` and `tail`
+
+`head` returns the first element wrapped with a `Maybe`.
+
+```ruby
+require 'dry/monads/list'
+
+M = Dry::Monads
+
+M::List[1, 2, 3, 4].head # => Some(1)
+M::List[1, 2, 3, 4].tail # => List[2, 3, 4]
+```
+
+### `traverse`
+
+Traverses the list with a block (or without it). This method "flips" List structure with the given monad (obtained from the type).
+
+**Note that traversing requires the list to be typed.**
+
+```ruby
+require 'dry/monads/list'
+
+M = Dry::Monads
+
+M::List[M::Success(1), M::Success(2)].typed(M::Result).traverse # => Success([1, 2])
+M::List[M::Maybe(1), M::Maybe(nil), M::Maybe(3)].typed(M::Maybe).traverse # => None
+
+# also, you can use fmap with #traverse
+
+M::List[1, 2].fmap { |x| M::Success(x) }.typed(M::Result).traverse # => Success([1, 2])
+M::List[1, nil, 3].fmap { |x| M::Maybe(x) }.typed(M::Maybe).traverse # => None
+```

data/docsite/source/maybe.html.md

@@ -0,0 +1,146 @@
+---
+title: Maybe
+layout: gem-single
+name: dry-monads
+---
+
+The `Maybe` monad is used when a series of computations could return `nil` at any point.
+
+### `bind`
+
+Applies a block to a monadic value. If the value is `Some` then calls the block passing the unwrapped value as an argument. Returns itself if the value is `None`.
+
+```ruby
+extend Dry::Monads[:maybe]
+
+maybe_user = Maybe(user).bind do |u|
+  Maybe(u.address).bind do |a|
+    Maybe(a.street)
+  end
+end
+
+# If user with address exists
+# => Some("Street Address")
+# If user or address is nil
+# => None()
+
+# You also can pass a proc to #bind
+
+add_two = -> (x) { Maybe(x + 2) }
+
+Maybe(5).bind(add_two).bind(add_two) # => Some(9)
+Maybe(nil).bind(add_two).bind(add_two) # => None()
+
+```
+
+### `fmap`
+
+Similar to `bind` but works with blocks/methods that returns unwrapped values (i.e. not `Maybe` instances).
+
+```ruby
+extend Dry::Monads[:maybe]
+
+Maybe(10).fmap { |x| x + 5 }.fmap { |y| y * 2 }
+# => Some(30)
+```
+
+In 1.x `Maybe#fmap` coerces `nil` values returned from blocks to `None`. This behavior will be changed in 2.0. This will be done because implicit coercion violates the functor laws which in order can lead to a surpising (not in a good sense) behavior. If you expect a block to return `nil`, use `Maybe#maybe` added in 1.3.
+
+### `maybe`
+
+Almost identical to `Maybe#fmap` but maps `nil` to `None`. This is similar to how the `&.` operator works in Ruby but does wrapping:
+
+```ruby
+extend Dry::Monads[:maybe]
+
+Maybe(user).maybe(&:address).maybe(&:street)
+
+# If user with address exists
+# => Some("Street Address")
+# If user or address is nil
+# => None()
+```
+
+### `value!`
+
+You always can extract the result by calling `value!`. It will raise an error if you call it on `None`. You can use `value_or` for safe unwrapping.
+
+```ruby
+extend Dry::Monads[:maybe]
+
+Some(5).fmap(&:succ).value! # => 6
+
+None().fmap(&:succ).value!
+# => Dry::Monads::UnwrapError: value! was called on None
+
+```
+
+### `value_or`
+
+Has one argument, unwraps the value in case of `Some` or returns the argument value back in case of `None`. It's a safe and recommended way of extracting values.
+
+```ruby
+extend Dry::Monads[:maybe]
+
+add_two = -> (x) { Maybe(x + 2) }
+
+Maybe(5).bind(add_two).value_or(0) # => 7
+Maybe(nil).bind(add_two).value_or(0) # => 0
+
+Maybe(nil).bind(add_two).value_or { 0 } # => 0
+```
+
+### `or`
+
+The opposite of `bind`.
+
+```ruby
+extend Dry::Monads[:maybe]
+
+add_two = -> (x) { Maybe(x + 2) }
+
+Maybe(5).bind(add_two).or(Some(0)) # => Some(7)
+Maybe(nil).bind(add_two).or(Some(0)) # => Some(0)
+
+Maybe(nil).bind(add_two).or { Some(0) } # => Some(0)
+```
+
+### `and`
+
+Two values can be chained using `.and`:
+
+```ruby
+extend Dry::Monads[:maybe]
+
+Some(5).and(Some(10)) { |x, y| x + y } # => Some(15)
+Some(5).and(None) { |x, y| x + y }     # => None()
+None().and(Some(10)) { |x, y| x + y }  # => None()
+
+Some(5).and(Some(10)) # => Some([5, 10])
+Some(5).and(None())   # => None()
+```
+
+### `flatten`
+
+To remove one level of nesting:
+
+```ruby
+extend Dry::Monads[:maybe]
+
+Some(Some(10)).flatten # => Some(10)
+Some(None()).flatten   # => None()
+None().flatten         # => None()
+```
+
+### `to_result`
+
+Maybe values can be converted to Result objects:
+
+```ruby
+extend Dry::Monads[:maybe, :result]
+
+Some(10).to_result # => Success(10)
+None().to_result # => Failure()
+None().to_result(:error) # => Failure(:error)
+None().to_result { :block_value } # => Failure(:block_value)
+```

data/docsite/source/pattern-matching.html.md

@@ -0,0 +1,68 @@
+---
+title: Pattern matching
+layout: gem-single
+name: dry-monads
+---
+
+Ruby 2.7 introduces pattern matchings, it is nicely supported by dry-monads 1.3+.
+
+### Matching Result values
+
+```ruby
+# presumably you do it in a class with `include Dry::Monads[:result]`
+
+case value
+in Success(Integer => x)
+  # x is bound to an integer
+in Success[:created, user] # alternatively: Success([:created, user])
+  # user is bound to the second member
+in Success(Date | Time)
+  # date or time object
+in Success([1, *])
+  # any array starting with 1
+in Success(String => s) if s.size < 100
+  # only if `s` is short enough
+in Success({ counter: Integer })
+  # matches Success(counter: 50)
+  # doesn't match Success(counter: 50, extra: 50)
+in Success({ user: User, account: Account => user_account, ** })
+  # matches Success(user: User.new(...), account: Account.new(...), else: ...)
+  # user_account is bound to the value of the `:account` key
+in Success()
+  # corresponds to Success(Unit)
+in Success(_)
+  # general success
+in Failure[:user_not_found]
+  # Failure([:user_not_found])
+in Failure[error_code, *payload]
+  # ...
+end
+```
+
+In the sippet above, the patterns will be tried sequentially. If `value` doesn't match any pattern, an error will be thrown.
+
+### Matching Maybe
+
+```ruby
+case value
+in Some(Integer => x)
+  # x is an integer
+in Some(Float | String)
+  # ...
+in None
+  # ...
+end
+```
+
+### Matching List
+
+```ruby
+case value
+in List[Integer]
+  # any list of size 1 with an integer
+in List[1, 2, 3, *]
+  # list with size >= 3 starting with 1, 2, 3
+in List[]
+  # empty list
+end
+```