dry-effects 0.1.2 → 0.2.0

data/docsite/source/effects/defer.html.md

@@ -1,130 +0,0 @@
----
-title: Deferred execution
-layout: gem-single
-name: dry-effects
----
-
-`Defer` adds three methods for working with deferred code execution:
-
-- `defer` accepts a block and executes it (potentially) on a thread pool. It returns an object that can be awaited with `wait`. These objects are `Promise`s made by `concurrent-ruby`. You can use their API, but it's not fully supported and tested in conjunction with effects.
-- `wait` accepts a promise or an array of promises returned by `defer` and returns their values. The method blocks the current thread until all values are available.
-- `later` postpones block execution until the handler is finished (see examples below).
-
-### Defer
-
-A simple example:
-
-```ruby
-class CreateUser
-  include Dry::Effects.Resolve(:user_repo, :send_invitation)
-  include Dry::Effects.Defer
-
-  def call(values)
-    user = user_repo.create(values)
-    defer { send_invitation.(user) }
-    user
-  end
-end
-```
-
-In the code above, `send_invitation` is run on a thread pool. It's the simplest way to run code concurrently.
-
-Code within the `defer` block can use some effects but not all of them. For instance, `Interrupt` is not supported because you cannot return from one thread to another. This is a limitation of Ruby and threads in general.
-
-### Handling
-
-The default handler uses `concurrent-ruby` to do the heavy lifting. As an option, it accepts the executor—usually a thread pool where the code will be run.
-
-> Three special values are also supported: `:io` returns the global pool for long, blocking (IO) tasks, `:fast` returns the global pool for short, fast operations, and `:immediate` returns the global ImmediateExecutor object.
-
-By default, `Dry::Effects::Handler.Defer` uses `:io`.
-
-```ruby
-class HandleDefer
-  include Dry::Effects::Handler.Defer(executor: :immediate)
-
-  def initialize(app)
-    @app = app
-  end
-
-  def call(env)
-    # defer tasks in @app will be run on the same thread
-    with_defer { @app.(env) }
-  end
-end
-```
-
-The executor can be passed directly to `with_defer`:
-
-```ruby
-def call(env)
-  with_defer(executor: :fast) { @app.(env) }
-end
-```
-
-### Using null executor
-
-For skipping deferred tasks, create a mocked executor
-
-```ruby
-require 'concurrent/executor/executor_service'
-
-NullExecutor = Object.new.extend(Concurrent::ExecutorService).tap do |null|
-  def null.post
-  end
-end
-```
-
-and provide it in middleware
-
-```ruby
-class HandleDefer
-  include Dry::Effects::Handler.Defer
-  include Dry::Effects::Handler.Env(:environment)
-
-  def initialize(app)
-    @app = app
-  end
-
-  def call(env)
-    with_defer(executor: executor) { @app.(env) }
-  end
-
-  def executor
-    environment.equal?(:test) ? NullExecutor : :io
-  end
-end
-```
-
-### Later
-
-`later` doesn't return a result that can be awaited. Instead, it starts deferred blocks on handler exit. Consider this example:
-
-```ruby
-class CreateUser
-  def call(values)
-    user_repo.transaction do
-      user = user_repo.create(values)
-      defer { send_invitation.(user) }
-      user_account = account_repo.create(user)
-      user
-    end
-  end
-end
-```
-
-There is no guarantee `send_invitation` will be run _after_ the transaction finishes. It may lead to race conditions or anomalies. If `account_repo.create` fails with an exception, the transaction will be rolled back yet the invitation will be sent!
-
-`later` captures the block but doesn't run it:
-
-```ruby
-later { send_invitation.(user) }
-```
-
-The invitaition will be sent when `with_defer` exits:
-
-```ruby
-with_defer { @app.(env) }
-```
-
-It usually happens outside of any transaction so that anomalies don't occur.

data/docsite/source/effects/env.html.md

@@ -1,144 +0,0 @@
----
-title: Environment
-layout: gem-single
-name: dry-effects
----
-
-Configuring code via `ENV` can be handy, but testing it by mutating a global constant is usually not. Env is similar to Reader but exists for passing simple key-value pairs, precisely what `ENV` does.
-
-### Providing environment
-
-```ruby
-require 'dry/effects'
-
-class EnvironmentMiddleware
-  include Dry::Effects::Handler.Env(environment: ENV['RACK_ENV'])
-
-  def initialize(app)
-    @app = app
-  end
-
-  def call(env)
-    with_env { @app.(env) }
-  end
-end
-```
-
-### Using environment
-
-By default, `Effects.Env` creates accessor to keys with the same name:
-
-```ruby
-class CreateUser
-  include Dry::Effects.Env(:environment)
-
-  def call(...)
-    #
-    log unless environemnt.eql?('test')
-  end
-end
-```
-
-But you can pass a hash and use arbitrary method names:
-
-```ruby
-class CreateUser
-  include Dry::Effects.Env(env: :environment)
-
-  def call(...)
-    #
-    log unless env.eql?('test')
-  end
-end
-```
-
-### Interaction with `ENV`
-
-The Env handler will search for keys in `ENV` as a fallback:
-
-```ruby
-class SendRequest
-  include Dry::Effects.Env(endpoint: 'THIRD_PARTY')
-
-  def call(...)
-    # some code using `endpoint`
-  end
-end
-```
-
-In a production environment, it would be enough to pass `THIRD_PARTY` an environment variable and call `with_env` at the top of the application:
-
-```ruby
-require 'dry/effects'
-
-class SidekiqEnvMiddleware
-  include Dry::Effects::Handler.Env
-
-  def call(_worker, _job, _queue, &block)
-    with_env(&block)
-  end
-end
-
-Sidekiq.configure_server do |config|
-  config.server_middleware do |chain|
-    chain.add SidekiqEnvMiddleware
-  end
-end
-```
-
-In tests, you can pass `THIRD_PARTY` without modifying `ENV`:
-
-```ruby
-RSpec.describe SendRequest do
-  include Dry::Effects::Handler.Env
-
-  subject(:send_request) { described_class.new }
-
-  let(:endpoint) { "fake server" }
-
-  around { with_env('THIRD_PARTY' => endpoint, &ex) }
-
-  it 'sends a request to a fake server' do
-    send_request.(...)
-  end
-end
-```
-
-### Overriding handlers
-
-By passing `overridable: true` you can override values provided by the nested handler:
-
-```ruby
-class Application
-  include Dry::Effects.Env(:foo)
-
-  def call
-    puts foo
-  end
-end
-
-class ProvidingContext
-  include Dry::Effects::Handler.Env
-
-  def call
-    with_env({ foo: 100 }, overridable: true) { yield }
-  end
-end
-
-class OverridingContext
-  include Dry::Effects::Handler.Env
-
-  def call
-    with_env(foo: 200) { yield }
-  end
-end
-
-overriding = OverridingContext.new
-providing = ProvidingContext.new
-app = Application.new
-
-overriding.() { providing.() { app.() } }
-# prints 200, coming from overriding context
-```
-
-Again, this is useful for testing, you pass `overridable: true` in the test environment and override environment values in specs.

data/docsite/source/effects/interrupt.html.md

@@ -1,109 +0,0 @@
----
-title: Interrupt
-layout: gem-single
-name: dry-effects
----
-
-Interrupt is an effect with the semantics of `raise`/`rescue` or `throw`/`catch`. It's added for consistency and compatibility with other effects. Underneath, it uses `raise` + `rescue` so that application code can detect the bubbling.
-
-### Basic usage
-
-If you know what exceptions are, this should look familiar:
-
-```ruby
-require 'dry/effects'
-
-class RunDivision
-  include Dry::Effects::Handler.Interrupt(:division_by_zero, as: :catch_zero_division)
-
-  def call
-    error, answer = catch_zero_division do
-      yield
-    end
-
-    if error
-      :error
-    else
-      answer
-    end
-  end
-end
-
-class Divide
-  include Dry::Effects.Interrupt(:division_by_zero)
-
-  def call(dividend, divisor)
-    if divisor.zero?
-      division_by_zero
-    else
-      dividend / divisor
-    end
-  end
-end
-
-run = RunDivision.new
-divide = Divide.new
-
-app = -> a, b { run.() { divide.(a, b) } }
-
-app.(10, 2) # => 5
-app.(1, 0) # => :error
-```
-
-The handler returns a flag indicating whether there was an interruption. `false` means the block was run without interruption, `true` stands for the code was interrupted at some point.
-
-### Payload
-
-Interruption can have a payload:
-
-```ruby
-class Callee
-  include Dry::Effects.Interrupt(:halt)
-
-  def call
-    halt :foo
-  end
-end
-
-class Caller
-  include Dry::Effects::Handler.Interrupt(:halt, as: :catch_halt)
-
-  def call
-    _, result = catch_halt do
-      yield
-      :bar
-    end
-
-    result
-  end
-end
-
-caller = Caller.new
-callee = Callee.new
-
-caller.() { callee.() } # => :foo
-caller.() { } # => :bar
-```
-
-### Composition
-
-Every Interrupt effect has to have an identifier so that they don't overlap. It's an equivalent of exception types. You can nest handlers with different identifiers; they will work just as you would expect:
-
-```ruby
-class Catcher
-  include Dry::Effects::Handler(:div_error, as: :catch_div)
-  include Dry::Effects::Handler(:sqrt_error, as: :catch_sqrt)
-
-  def call
-    _, div_result = catch_div do
-      _, sqrt_result = catch_sqrt do
-        yield
-      end
-
-      sqrt_result
-    end
-
-    div_result
-  end
-end
-```

data/docsite/source/effects/parallel.html.md

@@ -1,25 +0,0 @@
----
-title: Parallel execution
-layout: gem-single
-name: dry-effects
----
-
-There are two effects for using parallelism:
-
-- `par` creates a unit of parallel execution;
-- `join` combines an array of units to the array of their results.
-
-`par`/`join` is almost identical to `defer`/`wait` from [`Defer`](/gems/dry-effects/0.1/effects/defer), the difference is in the semantics. `defer` is not supposed to be always awaited, it's usually fired-and-forgotten. On the contrary, `par` is meant to be `join`ed at some point.
-
-```ruby
-class MakeRequests
-  include Dry::Effects.Resolve(:make_request)
-
-  def call(urls)
-    # Run every request in parallel and combine their results
-    urls.map { |url| par { make_request.(url) } }.then { |pars| join(pars) }
-  end
-end
-```
-
-Just as [`Defer`](/gems/dry-effects/0.1/effects/defer), `Parallel` uses `concurrent-ruby` under the hood.

data/docsite/source/effects/reader.html.md

@@ -1,126 +0,0 @@
----
-title: Reader
-layout: gem-single
-name: dry-effects
----
-
-Reader is the simplest effect. It passes a value down to the stack.
-
-```ruby
-require 'dry/effects'
-
-class SetLocaleMiddleware
-  include Dry::Effects::Handler.Reader(:locale)
-
-  def initialize(app)
-    @app = app
-  end
-
-  def call(env)
-    with_locale(detect_locale(env)) do
-      @app.(env)
-    end
-  end
-
-  def detect_locale(env)
-    # arbitrary detection logic
-  end
-end
-
-### Anywhere in the app
-
-class GreetUser
-  include Dry::Effects.Reader(:locale)
-
-  def call(user)
-    case locale
-    when :en then "Hello #{user.name}"
-    when :de then "Hallo #{user.name}"
-    when :ru then "Привет, #{user.name}"
-    when :it then "Ciao #{user.name}"
-    end
-  end
-end
-```
-
-### Testing with Reader
-
-If you run `GreetUser#call` without a Reader handler, it will raise an error. For unit tests you'll need some wrapping code:
-
-```ruby
-RSpec.describe GreetUser do
-  include Dry::Effects::Handler.Reader(:locale)
-
-  subject(:greet) { described_class.new }
-
-  let(:user) { double(:user, name: 'John') }
-
-  it 'uses the current locale to greet the user' do
-    examples = {
-      en: 'Hello John',
-      de: 'Hallo John',
-      ru: 'Привет, John',
-      it: 'Ciao John'
-    }
-
-    examples.each do |locale, expected_greeting|
-      with_locale(locale) do
-        expect(greet.(user)).to eql(expected_greeting)
-      end
-    end
-  end
-end
-```
-
-You can provide locale in an `around(:each)` hook:
-
-```ruby
-require 'dry/effects'
-
-# Build a provider object with .call interface
-locale_provider = Object.new.extend(Dry::Effects::Handler.Reader(:locale, as: :call))
-
-RSpec.configure do |config|
-  config.around(:each) do |ex|
-    locale_provider.(:en, &ex)
-  end
-end
-```
-
-### Nesting readers
-
-As a general rule, if there are two handlers in the stack, the nested takes precedence:
-
-```ruby
-require 'dry/effects'
-
-extend Dry::Effects::Handler.Reader(:locale)
-extend Dry::Effects.Reader(:locale)
-
-with_locale(:en) { with_locale(:de) { locale } } # => :de
-```
-
-### Mixing readers
-
-Every Reader has an identifier. Handlers with different identifiers won't interfere:
-
-```ruby
-require 'dry/effects'
-
-extend Dry::Effects::Handler.Reader(:locale)
-extend Dry::Effects::Handler.Reader(:context)
-extend Dry::Effects.Reader(:locale)
-extend Dry::Effects.Reader(:context)
-
-with_locale(:en) { with_context(:background) { [locale, context] } } # => [:en, :background]
-# Order doesn't matter:
-with_context(:background) { with_locale(:en) { [locale, context] } } # => [:en, :background]
-```
-
-### Relation to State
-
-Reader is part of the [State](/gems/dry-effects/0.1/effects/state) effect.
-
-### Tradeoffs of implicit passing
-
-Passing values implicitly is not good or bad by itself; you should consider how it affects your code in every case. Providing the current locale is a good example where reader effect can be justified. On the other hand, passing optional values such as the IP-address of the current user should be done explicitly because they are not always present (consider background jobs, rake tasks, etc.).