dry-monads 1.3.1 → 1.3.2

data/docsite/source/result.html.md

@@ -0,0 +1,190 @@
+---
+title: Result
+layout: gem-single
+name: dry-monads
+---
+
+The `Result` monad is useful to express a series of computations that might
+return an error object with additional information.
+
+The `Result` mixin has two type constructors: `Success` and `Failure`. The `Success`
+can be thought of as "everything went success" and the `Failure` is used when
+"something has gone wrong".
+
+### `bind`
+
+Use `bind` for composing several possibly-failing operations:
+
+```ruby
+require 'dry/monads'
+
+class AssociateUser
+  include Dry::Monads[:result]
+
+  def call(user_id:, address_id:)
+    find_user(user_id).bind do |user|
+      find_address(address_id).fmap do |address|
+        user.update(address_id: address.id)
+      end
+    end
+  end
+
+  private
+
+  def find_user(id)
+    user = User.find_by(id: id)
+
+    if user
+      Success(user)
+    else
+      Failure(:user_not_found)
+    end
+  end
+
+  def find_address(id)
+    address = Address.find_by(id: id)
+
+    if address
+      Success(address)
+    else
+      Failure(:address_not_found)
+    end
+  end
+end
+
+AssociateUser.new.(user_id: 1, address_id: 2)
+```
+
+### `fmap`
+
+An example of using `fmap` with `Success` and `Failure`.
+
+```ruby
+extend Dry::Monads[:result]
+
+result = if foo > bar
+  Success(10)
+else
+  Failure("wrong")
+end.fmap { |x| x * 2 }
+
+# If everything went success
+result # => Success(20)
+# If it did not
+result # => Failure("wrong")
+
+# #fmap accepts a proc, just like #bind
+
+upcase = :upcase.to_proc
+
+Success('hello').fmap(upcase) # => Success("HELLO")
+```
+
+### `value_or`
+
+`value_or` is a safe and recommended way of extracting values.
+
+```ruby
+extend Dry::Monads[:result]
+
+Success(10).value_or(0) # => 10
+Failure('Error').value_or(0) # => 0
+```
+
+### `value!`
+
+If you're 100% sure you're dealing with a `Success` case you might use `value!` for extracting the value without providing a default. Beware, this will raise an exception if you call it on `Failure`.
+
+```ruby
+extend Dry::Monads[:result]
+
+Success(10).value! # => 10
+Failure('Error').value!
+# => Dry::Monads::UnwrapError: value! was called on Failure
+```
+
+### `or`
+
+An example of using `or` with `Success` and `Failure`.
+
+```ruby
+extend Dry::Monads[:result]
+
+Success(10).or(Success(99)) # => Success(10)
+Failure("error").or(Failure("new error")) # => Failure("new error")
+Failure("error").or { |err| Failure("new #{err}") } # => Failure("new error")
+```
+
+### `failure`
+
+Use `failure` for unwrapping the value from a `Failure` instance.
+
+```ruby
+extend Dry::Monads[:result]
+
+Failure('Error').failure # => "Error"
+```
+
+### `to_maybe`
+
+Sometimes it's useful to turn a `Result` into a `Maybe`.
+
+```ruby
+extend Dry::Monads[:result, :maybe]
+
+result = if foo > bar
+  Success(10)
+else
+  Failure("wrong")
+end.to_maybe
+
+# If everything went success
+result # => Some(10)
+# If it did not
+result # => None()
+```
+
+### `failure?` and `success?`
+
+You can explicitly check the type by calling `failure?` or `success?` on a monadic value.
+
+### `either`
+
+`either` maps a `Result` to some type by taking two callables, for `Success` and `Failure` cases respectively:
+
+```ruby
+Success(1).either(-> x { x + 1 }, -> x { x + 2 }) # => 2
+Failure(1).either(-> x { x + 1 }, -> x { x + 2 }) # => 3
+```
+
+
+### Adding constraints to `Failure` values.
+You can add type constraints to values passed to `Failure`. This will raise an exception if value doesn't meet the constraints:
+
+```ruby
+require 'dry-types'
+
+module Types
+  include Dry.Types()
+end
+
+class Operation
+  Error = Types.Instance(RangeError)
+  include Dry::Monads::Result(Error)
+
+  def call(value)
+    case value
+    when 0..1
+      Success(:success)
+    when -Float::INFINITY..0, 1..Float::INFINITY
+      Failure(RangeError.new('Error'))
+    else
+      Failure(TypeError.new('Type error'))
+    end
+  end
+end
+
+Operation.new.call(0.5) # => Success(:success)
+Operation.new.call(5) # => Failure(#<RangeError: Error>)
+Operation.new.call("5") # => Dry::Monads::InvalidFailureTypeError: Cannot create Failure from #<TypeError: Type error>, it doesn't meet the constraints
+```

data/docsite/source/task.html.md

@@ -0,0 +1,126 @@
+---
+title: Task
+layout: gem-single
+name: dry-monads
+---
+
+`Task` represents an asynchronous computation. It is similar to the `IO` type in a sense it can be used to wrap side-effectful actions. `Task`s are usually run on a thread pool but also can be executed immediately on the current thread. Internally, `Task` uses `Promise` from the [`concurrent-ruby`](https://github.com/ruby-concurrency/concurrent-ruby) gem, basically it's a thin wrapper with a monadic interface which makes it easily composable with other monads.
+
+### `Task::Mixin`
+
+Basic usage.
+
+```ruby
+require 'dry/monads'
+
+class PullUsersWithPosts
+  include Dry::Monads[:task]
+
+  def call
+    # Start two tasks running concurrently
+    users = Task { fetch_users }
+    posts = Task { fetch_posts }
+
+    # Combine two tasks
+    users.bind { |us| posts.fmap { |ps| [us, ps] } }
+  end
+
+  def fetch_users
+    sleep 3
+    [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]
+  end
+
+  def fetch_posts
+    sleep 2
+    [
+      { id: 1, user_id: 1, name: 'Hello from John' },
+      { id: 2, user_id: 2, name: 'Hello from Jane' },
+    ]
+  end
+end
+
+# PullUsersWithPosts instance
+pull = PullUsersWithPosts.new
+
+# Spin up two tasks
+task = pull.call
+
+task.fmap do |users, posts|
+  puts "Users: #{ users.inspect }"
+  puts "Posts: #{ posts.inspect }"
+end
+
+puts "----" # this will be printed before the lines above
+```
+
+### Executors
+
+Tasks are performed by executors, there are three executors predefined by `concurrent-ruby` identified by symbols:
+
+- `:fast` – for fast asynchronous tasks, uses a thread pool
+- `:io` – for long IO-bound tasks, uses a thread pool, different from `:fast`
+- `:immediate` – runs tasks immediately, on the current thread. Can be used in tests or for other purposes
+
+You can create your own executors, check out the [docs](http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent.html) for more on this.
+
+The following examples use the Ruby 2.5+ syntax which allows passing a block to `.[]`.
+
+```ruby
+Task[:io] { do_http_request }
+
+Task[:fast] { cpu_intensive_computation }
+
+Task[:immediate] { unsafe_io_operation }
+
+# You can pass an executor object
+Task[my_executor] { ... }
+```
+
+### Exception handling
+
+All exceptions happening in `Task` are captured, even if you're using the `:immediate` executor, they won't be re-raised.
+
+```ruby
+io_fail = Task[:io] { 1/0 }
+io_fail # => Task(error=#<ZeroDivisionError: divided by 0>)
+
+immediate_fail = Task[:immediate] { 1/0 }
+immediate_fail # => Task(error=#<ZeroDivisionError: divided by 0>)
+```
+
+You can process failures with `or` and `or_fmap`:
+
+```ruby
+Task[:immediate] { 1/0 }.or { M::Task[:immediate] { 0 } } # => Task(value=0)
+Task[:immediate] { 1/0 }.or_fmap { 0 } # => Task(value=0)
+```
+
+### Extracting result
+
+Getting the result of a task is an unsafe operation, it blocks the current thread until the task is finished, then returns the value or raises an exception if the evaluation wasn't sucessful. It effectively cancels all niceties of tasks so you shouldn't use it in production code.
+
+```ruby
+Task { 0 }.value! # => 0
+Task { 1/0 }.value! # => ZeroDivisionError: divided by 0
+```
+
+You can wait for a task to complete, the `wait` method accepts an optional timeout. `.wait` returns the task back, without unwrapping the result so it's a blocking yet safe operation:
+
+```ruby
+Task[:io] { 2 }.wait(1) # => Task(value=2)
+Task[:io] { sleep 2; 2 }.wait(1) # => Task(?)
+
+# (?) denotes an unfinished computation
+```
+
+### Conversions
+
+Tasks can be converted to other monads but keep in mind that all conversions block the current thread:
+
+```ruby
+Task[:io] { 2 }.to_result # => Success(2)
+Task[:io] { 1/0 }.to_result # => Failure(#<ZeroDivisionError: divided by 0>)
+
+Task[:io] { 2 }.to_maybe # => Some(2)
+Task[:io] { 1/0 }.to_maybe # => None
+```

data/docsite/source/tracing-failures.html.md

@@ -0,0 +1,32 @@
+---
+title: Tracing failures
+layout: gem-single
+name: dry-monads
+---
+
+"Left" values of right-biased monads like `Maybe` and `Result` (as in, `None()` and `Failure()`) ignore blocks passed to `fmap` and `bind`. Because of this, these values travel across the application without any modification. If the place where a `Failure` was constructed is burried somewhere deep in the app or library code it may be pretty hard to find out where exactly the error occurred.
+
+This is a noticable downside compared to "good" old exceptions. To address it, every `Failure(...)` and `None()` value tracks the line where it was created:
+
+```ruby
+# create_user.rb
+require 'dry/monads'
+
+class CreateUser
+  include Dry::Monads[:result]
+
+  def call
+    Failure(:no_luck)
+  end
+end
+```
+
+```ruby
+require 'create_user'
+
+create_user = CreateUser.new
+create_user.()       # => Failure(:no_luck)
+create_user.().trace # => .../create_user.rb:8:in `call'
+```
+
+Note that the trace stores only one line of the stack so it shouldn't ever be a performance issue.

data/docsite/source/try.html.md

@@ -0,0 +1,76 @@
+---
+title: Try
+layout: gem-single
+name: dry-monads
+---
+
+Rescues a block from an exception. The `Try` monad is useful when you want to wrap some code that can raise exceptions of certain types. A common example is making an HTTP request or querying a database.
+
+```ruby
+require 'dry/monads'
+
+class ExceptionalLand
+  include Dry::Monads[:try]
+
+
+  def call
+    res = Try { 10 / 2 }
+    res.value! if res.value?
+    # => 5
+
+    res = Try { 10 / 0 }
+    res.exception if res.error?
+    # => #<ZeroDivisionError: divided by 0>
+
+    # By default Try catches all exceptions inherited from StandardError.
+    # However you can catch only certain exceptions like this
+    Try[NoMethodError, NotImplementedError] { 10 / 0 }
+    # => raised ZeroDivisionError: divided by 0 exception
+  end
+end
+```
+
+It is better if you pass a list of expected exceptions which you are sure you can process. Catching exceptions of all types is considered bad practice.
+
+The `Try` monad consists of two types: `Value` and `Error`. The first is returned when code did not raise an error and the second is returned when the error was captured.
+
+### `bind`
+
+Allows you to chain blocks that can raise exceptions.
+
+```ruby
+Try[NetworkError, DBError] { grap_user_by_making_request }.bind { |user| user_repo.save(user) }
+
+# Possible outcomes:
+# => Value(persisted_user)
+# => Error(NetworkError: request timeout)
+# => Error(DBError: unique constraint violated)
+```
+
+### `fmap`
+
+Works exactly the same way as `Result#fmap` does.
+
+```ruby
+require 'dry/monads'
+
+class ExceptionalLand
+  include Dry::Monads[:try]
+
+  def call
+    Try { 10 / 2 }.fmap { |x| x * 3 }
+    # => 15
+
+    Try[ZeroDivisionError] { 10 / 0 }.fmap { |x| x * 3 }
+    # => Failure(ZeroDivisionError: divided by 0)
+  end
+end
+```
+
+### `value!` and `exception`
+
+Use `value!` for unwrapping a `Success` and `exception` for getting error object from a `Failure`.
+
+### `to_result` and `to_maybe`
+
+`Try`'s `Value` and `Error` can be transformed to `Success` and `Failure` correspondingly by calling `to_result` and to `Some` and `None` by calling `to_maybe`. Keep in mind that by transforming `Try` to `Maybe` you lose the information about an exception so be sure that you've processed the error before doing so.

data/docsite/source/unit.html.md

@@ -0,0 +1,36 @@
+---
+title: Unit
+layout: gem-single
+name: dry-monads
+---
+
+Some constructors do not require you to pass a value. As a default they use `Unit`, a special singleton value:
+
+```ruby
+extend Dry::Monads[:result]
+
+Success().value! # => Unit
+```
+
+`Unit` doesn't have any special properties or methods, it's similar to `nil` except for it is not i.e. `if Unit` passes.
+
+`Unit` is usually excluded from the output:
+
+```ruby
+extend Dry::Monads[:result]
+
+# Outputs as "Success()" but technically it's "Success(Unit)"
+Success()
+```
+
+### Discarding values
+
+When the outcome of an operation is not a caller's concern, call `.discard`, it will map the wrapped value to `Unit`:
+
+```ruby
+extend Dry::Monads[:result]
+
+result = create_user # returns Success(#<User...>) or Failure(...)
+
+result.discard # => Maps Success(#<User ...>) to Success() but lefts Failure(...) intact
+```