dry-effects 0.1.0 → 0.1.1

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

@@ -0,0 +1,109 @@
+---
+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
+    success, answer = catch_zero_division do
+      yield
+    end
+
+    if success
+      answer
+    else
+      :error
+    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

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

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

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

@@ -0,0 +1,188 @@
+---
+title: Resolve (Dependency Injection)
+layout: gem-single
+name: dry-effects
+---
+
+Resolve is an effect for injecting dependencies. A simple usage example:
+
+```ruby
+require 'dry/effects'
+
+class CreateUser
+  include Dry::Effects.Resolve(:user_repo)
+
+  def call(values)
+    name = values.values_at(:first_name, :last_name).join(' ')
+    user_repo.create(values.merge(name: name))
+  end
+end
+```
+
+Providing `user_repo` in tests:
+
+```ruby
+RSpec.describe CreateUser do
+  # adds #provide
+  include Dry::Effects::Handler.Resolve
+
+  subject(:create_user) { described_class.new }
+
+  let(:user_repo) { double(:user_repo) }
+
+  it 'creates a user' do
+    expect(user_repo).to receive(:create).with(
+      first_name: 'John',
+      last_name: 'Doe',
+      name: 'John Doe'
+    )
+
+    provide(user_repo: user_repo) { create_user.(first_name: 'John', last_name: 'Doe') }
+  end
+end
+```
+
+Providing dependencies with middleware:
+
+```ruby
+class ProviderMiddleware
+  include Dry::Effects::Handler.Resolve
+
+  def initialize(app, dependencies)
+    @app = app
+    @dependencies = dependencies
+  end
+
+  def call(env)
+    provide(@dependencies) { @app.(env) }
+  end
+end
+```
+
+Then in `config.ru`:
+
+```ruby
+# ...some bootstrapping code ...
+
+use ProviderMiddleware, user_repo: UserRepo.new
+run Application.new
+```
+
+### Compatibility with `dry-container` and `dry-system`
+
+Any object that responds to `.key?` and `.[]` can be used for providing dependencies. Thus, the default Resolve provider is compatible with `dry-container` and `dry-system` out of the box.
+
+```ruby
+def call(env)
+  # Assuming App is a subclass of Dry::System::Container
+  provide(App) { @app.(env) }
+end
+```
+
+### Providing static values
+
+One can pass a container to the module builder:
+
+```ruby
+class ProviderMiddleware
+  include Dry::Effects::Handler.Resolve(Application)
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    # Here Application will be used for resolving dependencies
+    provide { @app.(env) }
+  end
+end
+```
+
+### Injecting many keys and using aliases
+
+```ruby
+require 'dry/effects'
+
+class CreateUser
+  include Dry::Effects.Resolve(
+    # Injected as .schema
+    # but resolved with 'operations.create_user.schema'
+    'operations.create_user.schema',
+    # Injected as .repo
+    # but resolved with 'repos.user_repo'
+    repo: 'repos.user_repo'
+  )
+
+  def call(values)
+    result = schema.(values)
+
+    if result.success?
+      user = repo.create(result.to_h)
+      [:ok, user]
+    else
+      [:err, result]
+    end
+  end
+end
+```
+
+### Overriding dependencies in test environment
+
+Sometimes you may want to push dependencies through an existing handler. This is normally needed for testing when you want to replace some dependencies in a test environment for an assembled app, like a Rack application. Passing `overridable: true` enables it:
+
+```ruby
+require 'dry/effects'
+
+class ProviderMiddleware
+  include Dry::Effects::Handler.Resolve
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    provide(Application, overridable: overridable?) { @app.(env) }
+  end
+
+  def overridable?
+    ENV['RACK_ENV'].eql?('test')
+  end
+end
+```
+
+Now in tests, you can override some dependencies at will:
+
+```ruby
+require 'dry/effects'
+require 'rack/test'
+
+RSpec.describe do
+  include Rack::Test::Methods
+  include Dry::Effects::Handler.Provider
+
+  let(:app) do
+    # building an assembled rack app
+  end
+
+  describe 'POST /users' do
+    let(:user_repo) { double(:user_repo) }
+
+    it 'creates a user' do
+      expect(user_repo).to receive(:create).with(
+        first_name: 'John', last_name: 'Doe'
+      ).and_return(1)
+
+      # Overriding one dependency
+      # It will only work if `overridable: true` is passed
+      # in the middleware
+      provide('repos.user_repo' => user_repo) do
+        post(
+          '/users',
+          JSON.dump(first_name: 'John', last_name: 'Doe'),
+          'CONTENT_TYPE' => 'application/json'
+        )
+      end
+    end
+  end
+end
+```