dry-monads 1.3.2 → 1.4.0

data/docsite/source/task.html.md

@@ -1,126 +0,0 @@
----
-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

@@ -1,32 +0,0 @@
----
-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

@@ -1,76 +0,0 @@
----
-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

@@ -1,36 +0,0 @@
----
-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
-```

data/docsite/source/validated.html.md

@@ -1,88 +0,0 @@
----
-title: Validated
-layout: gem-single
-name: dry-monads
----
-
-Suppose you've got a form to validate. If you are using `Result` combined with `Do` your code might look like this:
-
-```ruby
-require 'dry/monads'
-
-class CreateAccount
-  include Dry::Monads[:result, :do]
-
-  def call(form)
-    name = yield validate_name(form)
-    email = yield validate_email(form)
-    password = yield validate_password(form)
-
-    user = repo.create_user(
-      name: name,
-      email: email,
-      password: password
-    )
-
-    Success(user)
-  end
-
-  def validate_name(form)
-    # Success(name) or Failure(:invalid_name)
-  end
-
-  def validate_email(form)
-    # Success(email) or Failure(:invalid_email)
-  end
-
-  def validate_password(form)
-    # Success(password) or Failure(:invalid_password)
-  end
-end
-```
-
-If any of the validation steps fails the user will see an error. The problem is if `name` is not valid the user won't see errors about invalid `email` and `password`, if any. `Validated` circumvents this particular problem.
-
-`Validated` is actually not a monad but an applicative functor. This means you can't call `bind` on it. Instead, it can accumulate values in combination with `List`:
-
-```ruby
-require 'dry/monads'
-
-class CreateAccount
-  include Dry::Monads[:list, :result, :validated, :do]
-
-  def call(form)
-    name, email, password = yield List::Validated[
-      validate_name(form),
-      validate_email(form),
-      validate_password(form)
-    ].traverse.to_result
-
-    user = repo.create_user(
-      name: name,
-      email: email,
-      password: password
-    )
-
-    Success(user)
-  end
-
-  def validate_name(form)
-    # Valid(name) or Invalid(:invalid_name)
-  end
-
-  def validate_email(form)
-    # Valid(email) or Invalid(:invalid_email)
-  end
-
-  def validate_password(form)
-    # Valid(password) or Invalid(:invalid_password)
-  end
-end
-```
-
-Here all validations will be processed at once, if any of them fails the result will be converted to a `Failure` wrapping the `List` of errors:
-
-```ruby
-create_account.(form)
-# => Failure(List[:invalid_name, :invalid_email])
-```