dry-effects 0.1.0 → 0.1.1

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

@@ -0,0 +1,186 @@
+---
+title: Current Time
+layout: gem-single
+name: dry-effects
+---
+
+Obtaining the current time with `Time.now` is a classic example of a side effect. Code relying on accessing system time is harder to test. One possible solution is passing time around explicitly, but using effects can save you some typing depending on the case.
+
+Providing and obtaining the current time is straightforward:
+
+```ruby
+require 'dry/effects'
+
+class CurrentTimeMiddleware
+  include Dry::Effects::Handler.CurrentTime
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    # It will use Time.now internally once and set it fixed
+    with_current_time do
+      @app.(env)
+    end
+  end
+end
+
+###
+
+class CreateSubscription
+  include Dry::Efefcts.Resolve(:subscription_repo)
+  include Dry::Effects.CurrentTime
+
+  def call(values)
+    subscription_repo.create(
+      values.merge(start_at: current_time)
+    )
+  end
+end
+```
+
+### Providing time in tests
+
+A typical usage would be:
+
+```ruby
+require 'dry/effects'
+
+RSpec.configure do |config|
+  config.include Dry::Effects::Handler.CurrentTime
+  config.include Dry::Effects.CurrentTime
+
+  config.around { |ex| with_current_time(&ex) }
+end
+```
+
+Then anywhere in tests, you can use it:
+
+```ruby
+it 'uses current time as a start' do
+  subscription = create_subscription(...)
+  expect(subscription.start_at).to eql(current_time)
+end
+```
+
+To change the time, call `with_current_time` with a proc:
+
+```ruby
+it 'closes a subscription with current time' do
+  future = current_time + 86_400
+  closed_subscription = with_current_time(proc { future }) { close_subscription(subscription) }
+  expect(closed_subscription.closed_at).to eql(future)
+end
+```
+
+Wrapping time with a proc is required, read about generators below.
+
+### Time rounding
+
+`current_time` accepts an argument for rounding time values. It can be passed statically to the module builder or dynamically to the effect constructor:
+
+```ruby
+class CreateSubscription
+  include Dry::Effects.CurrentTime(round: 3)
+
+  def call(...)
+    # value will be rounded to milliseconds
+    current_time
+    # value will be rounded to microseconds
+    current_time(round: 6)
+  end
+end
+```
+
+### Time is fixed
+
+By default, calling `with_current_time` even without arguments will freeze the current time. This means `current_time` will return the same value during request processing etc.
+
+You can "unfix" time with passing `fixed: false` to the handler builder:
+
+```ruby
+include Dry::Effects::Handler.CurrentTime(fixed: false)
+```
+
+However, this is not recommended because it will make the behavior of `current_time` different in tests (where you pass a fixed value) and in a production environment.
+
+### Using a custom generator
+
+The default time provider accepts a custom generator which is a simple callable object. This way you can pass a proc with fixed time:
+
+```ruby
+frozen = Time.now
+with_fixed_time(proc { frozen }) do
+  # ...
+end
+```
+
+Or you can change time on every call:
+
+```ruby
+start = Time.now
+with_fixed_time(proc { start += 0.1 }) do
+  # ...
+end
+```
+
+### Discrete time shifts
+
+If you pass `step: x` to the handler, it will shift the current time on every access by `x`:
+
+```ruby
+with_fixed_time(step: 0.1) do
+  current_time # => ... 18:00:00.000
+  current_time # => ... 18:00:00.100
+  current_time # => ... 18:00:00.200
+end
+```
+
+You can also pass initial time:
+
+```ruby
+initial = Time.new(1970)
+with_fixed_time(initial: initial, step: 60) do
+  current_time # => 1970-01-01 00:00:00 +0000
+  current_time # => 1970-01-01 00:01:00 +0000
+  current_time # => 1970-01-01 00:02:00 +0000
+end
+```
+
+### Overriding handlers
+
+Handlers of current time can be overridden by an outer handler if you pass `overridable: true`:
+
+```ruby
+require 'dry/effects'
+
+class CurrentTimeMiddleware
+  include Dry::Effects::Handler.CurrentTime
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    with_current_time(overridable: ENV['RACK_ENV'].eql?('test')) do
+      @app.(env)
+    end
+  end
+end
+```
+
+It's usually done in tests:
+
+```ruby
+# Using global time
+frozen_time = Time.now
+
+puts "Running with time #{frozen_time.iso8601}" if ENV['CI']
+
+RSpec.configure do |config|
+  config.include Dry::Effects::Handler.CurrentTime
+  config.include(Module.new { define_method(:current_time) { frozen_time } })
+  config.around { |ex| with_current_time(proc { frozen_time }, &ex) }
+end
+```

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

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

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