dry-effects 0.1.2 → 0.2.0

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

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

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

@@ -1,178 +0,0 @@
----
-title: State
-layout: gem-single
-name: dry-effects
----
-
-State is a mutation effect. It allows [reading](/gems/dry-effects/0.1/effects/reader) and _writing_ non-local values.
-
-### Basic usage
-
-Handling code:
-
-```ruby
-require 'dry/effects'
-
-class CountCalls
-  include Dry::Effects::Handler.State(:counter)
-
-  def call
-    counter, result = with_counter(0) do
-      yield
-    end
-
-    puts "Counter: #{counter}"
-
-    result
-  end
-end
-```
-
-Using code:
-
-```ruby
-require 'dry/effects'
-
-class HeavyLifting
-  include Dry::Effects.State(:counter)
-
-  def call
-    self.counter += 1
-    # ... do heavy work ...
-  end
-end
-```
-
-Now it's simple to count calls by gluing two pieces:
-
-```ruby
-count_calls = CountCalls.new
-heavy_lifting = HeavyLifting.new
-
-count_calls.() { 1000.times { heavy_lifting.() }; :done }
-# Counter: 1000
-# => :done
-```
-
-### Handler interface
-
-As shown above, the State handler returns two values: the accumulated state and the return value of the block:
-
-```ruby
-include Dry::Effects::Handler.State(:state)
-
-def run(&block)
-  accumulated_state, result = with_state(initial_state) do
-    block.call
-  end
-
-  # result holds the return value of block.call
-
-  # accumulated_state refers to the last written value
-  # or initial_value if the state wasn't changed
-end
-```
-
-### Identifiers and mixing states
-
-All state handlers and effects have an identifier. Effects with different identifiers are compatible without limitations but swapping the handlers may change the result:
-
-```ruby
-require 'dry/effects'
-
-class Program
-  include Dry::Effects.State(:sum)
-  include Dry::Effects.State(:product)
-
-  def call
-    1.upto(10) do |i|
-      self.sum += i
-      self.product *= i
-    end
-
-    :done
-  end
-end
-
-program = Program.new
-
-extend Dry::Effects::Handler.State(:sum)
-extend Dry::Effects::Handler.State(:product)
-
-with_sum(0) { with_product(1) { program.call } }
-# => [55, [3628800, :done]]
-with_product(1) { with_sum(0) { program.call } }
-# => [3628800, [55, :done]]
-```
-
-### Relation to Reader
-
-A State handler eliminates Reader effects with the same identifier:
-
-```ruby
-require 'dry/effects'
-
-extend Dry::Effects::Handler.State(:counter)
-extend Dry::Effects.Reader(:counter)
-
-with_counter(100) { "Counter value is #{counter}" }
-# => [100, "Counter values is 100"]
-```
-
-### Not providing an initial value
-
-There are cases when an initial value cannot be provided. You can skip the initial value but in this case, reading it _before_ writing will raise an error:
-
-```ruby
-extend Dry::Effects::Handler.State(:user)
-extend Dry::Effects.State(:user)
-
-with_user { user }
-# => Dry::Effects::Errors::UndefinedStateError (+user+ is not defined, you need to assign it first by using a writer, passing initial value to the handler, or providing a fallback value)
-
-with_user do
-  self.user = 'John'
-
-  "Hello, #{user}"
-end
-# => ["John", "Hello, John"]
-```
-
-One example is testing middleware without mutating `env`:
-
-```ruby
-RSpec.describe AddingSomeMiddleware do
-  include Dry::Effects::Handler.State(:env)
-  include Dry::Effects.State(:env)
-
-  let(:app) do
-    lambda do |env|
-      self.env = env
-      [200, {}, ["ok"]]
-    end
-  end
-
-  subject(:middleware) { described_class.new(app) }
-
-  it 'adds SOME_KEY to env' do
-    captured_env, _ = middleware.({})
-
-    expect(captured_env).to have_key('SOME_KEY')
-  end
-end
-```
-
-### Default value for Reader effects
-
-When no initial value is given, you can use a block for providing a default value:
-
-```ruby
-extend Dry::Effects::Handler.State(:artist)
-extend Dry::Effects.State(:artist)
-
-with_artist { artist { 'Unknown Artist' } } # => "Unknown Artist"
-```
-
-### When to use?
-
-State is a classic example of an effect. However, using it often can make your code harder to follow.

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

@@ -1,42 +0,0 @@
----
-title: Timeout
-layout: gem-single
-name: dry-effects
----
-
-`Timeout` consists of two methods:
-
-- `timeout` returns an ever-decreasing number of seconds until this number reaches 0.
-- `timed_out?` checks if no time left.
-
-The handler provides the initial timeout and uses the monotonic time for counting down.
-
-A practical example is limiting the length of all external HTTP calls during request processing. Sample class for making HTTP requests in an application:
-
-```ruby
-class MakeRequest
-  include Dry::Effects.Timeout(:http)
-
-  def call(url)
-    HTTParty.get(url, timeout: timeout)
-  end
-end
-```
-
-Handling timeouts:
-
-```ruby
-class WithTimeout
-  def initialize(app)
-    @app = app
-  end
-
-  def call(env)
-    with_timeout(10.0) { @app.(env) }
-  rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
-    [504, {}, ["Gateway Timeout"]]
-  end
-end
-```
-
-The code above guarantees all requests made with `MakeRequest` during `@app.(env)` will finish within 10 seconds. If `@app` doesn't spend much time somewhere else, it gives a reasonably reliable hard limit on request processing.

data/docsite/source/effects.html.md

@@ -1,29 +0,0 @@
----
-title: Effects
-layout: gem-single
-name: dry-effects
-sections:
-  - reader
-  - state
-  - resolve
-  - cache
-  - current_time
-  - env
-  - interrupt
-  - defer
-  - timeout
-  - parallel
----
-
-`dry-effects` has a bunch of built-in effects and providers:
-
-- [Reader](/gems/dry-effects/0.1/effects/reader)
-- [State](/gems/dry-effects/0.1/effects/state)
-- [Resolve (Dependency Injection)](/gems/dry-effects/0.1/effects/resolve)
-- [Cache](/gems/dry-effects/0.1/effects/cache)
-- [Current Time](/gems/dry-effects/0.1/effects/current_time)
-- [Environment](/gems/dry-effects/0.1/effects/env)
-- [Interrupt](/gems/dry-effects/0.1/effects/interrupt)
-- [Deferred Execution](/gems/dry-effects/0.1/effects/defer)
-- [Timeout](/gems/dry-effects/0.1/effects/timeout)
-- [Parallel execution](/gems/dry-effects/0.1/effects/parallel)

data/docsite/source/index.html.md

@@ -1,212 +0,0 @@
----
-title: Introduction
-layout: gem-single
-type: gem
-name: dry-effects
-sections:
-  - effects
----
-
-`dry-effects` is a practical, production-oriented implementation of algebraic effects in Ruby.
-
-### Why?
-
-Algebraic effects are a powerful tool for writing composable and testable code in a safe way. Fundamentally, any effect consists of two parts: introduction (throwing effect) and elimination (handling effect with an _effect provider_). One of the many things you can do with them is sharing state:
-
-```ruby
-require 'dry/effects'
-
-class CounterMiddleware
-  # This adds a `counter` effect provider. It will handle (eliminate) effects
-  include Dry::Effects::Handler.State(:counter)
-
-  def initialize(app)
-    @app = app
-  end
-
-  def call(env)
-    # Calling `with_counter` makes the value available anywhere in `@app.call`
-    counter, response = with_counter(0) do
-      @app.(env)
-    end
-
-    # Once processing is complete, the result value
-    # will be stored in `counter`
-
-    response
-  end
-end
-
-### Somewhere deep in your app
-
-class CreatePost
-  # Adds counter accessor (by introducing state effects)
-  include Dry::Effects.State(:counter)
-
-  def call(values)
-    # Value is passed from middleware
-    self.counter += 1
-    # ...
-  end
-end
-```
-
-`CreatePost#call` can only be called when there's `with_counter` somewhere in the stack. If you want to test `CreatePost` separately, you'll need to use `with_counter` in tests too:
-
-```ruby
-require 'dry/effects'
-require 'posting_app/create_post'
-
-RSpec.describe CreatePost do
-  include Dry::Effects::Handler::State(:counter)
-
-  subject(:create_post) { described_class.new }
-
-  it 'updates the counter' do
-    counter, post = with_counter(0) { create_post.(post_values) }
-
-    expect(counter).to be(1)
-  end
-end
-```
-
-Any introduced effect must have a handler. If no handler found you'll see an error:
-
-```ruby
-CreatePost.new.({})
-# => Dry::Effects::Errors::MissingStateError (Value of +counter+ is not set, you need to provide value with an effect handler)
-```
-
-In a statically typed with support for algebraic effects you won't be able to run code without providing all required handlers, it'd be a type error.
-
-It may remind you using global state, but it's not actually global. It should instead be called "goto on steroids" or "goto made unharmful."
-
-### Cmp
-
-State sharing is one of many effects already supported; another example is comparative execution. Imagine you test a new feature that ideally shouldn't affect application responses.
-
-```ruby
-require 'dry/effects'
-
-class TestNewFeatureMiddleware
-  # `as:` renames handler method
-  include Dry::Effects::Handler.Cmp(:feature, as: :test_feature)
-
-  def initialize(app)
-    @app = app
-  end
-
-  def call(env)
-    without_feature, with_feature = test_feature do
-      @app.(env)
-    end
-
-    if with_feature != without_feature
-      # something is different!
-    end
-
-    without_feature
-  end
-end
-
-### Somewhere deep in your app
-
-class PostView
-  include Dry::Effects.Cmp(:feature)
-
-  def call
-    if feature?
-      # do render with feature
-    else
-      # do render without feature
-    end
-  end
-end
-```
-
-The `Cmp` provider will run your code twice so that you can compare the results and detect differences.
-
-### Composition
-
-So far effects haven't shown anything algebraic about themselves. Here comes composition. Any effect is composable with one another. Say we have code using both `State` and `Cmp` effects:
-
-```ruby
-require 'dry/effects'
-
-class GreetUser
-  include Dry::Effects.Cmp(:excitement)
-  include Dry::Effects.State(:greetings_given)
-
-  def call(name)
-    self.greetings_given += 1
-
-    if excitement?
-      "#{greetings_given}. Hello #{name}!"
-    else
-      "#{greetings_given}. Hello #{name}"
-    end
-  end
-end
-```
-
-It's a simple piece of code that requires a single argument and two effect handlers to run:
-
-```ruby
-class Context
-  include Dry::Effects::Handler.Cmp(:excitement, as: :test_excitement)
-  include Dry::Effects::Handler.State(:greetings_given)
-
-  def initialize
-    @greeting = GreetUser.new
-  end
-
-  def call(name)
-    test_excitement do
-      with_greetings_given(0) do
-        @greeting.(name)
-      end
-    end
-  end
-end
-
-Context.new.('Alice')
-# => [[1, "1. Hello Alice"], [1, "1. Hello Alice!"]]
-```
-
-The result is two branches with `excitement=false` and `excitement=true`. Every variant has its state handler and hence returns another array with the number of greetings given and the greeting. However, neither our code nor algebraic effects restrict the order in which the effects are meant to be handled so let's swap the handlers:
-
-```ruby
-class Context
-  # ...
-  def call(name)
-    with_greetings_given(0) do
-      test_excitement do
-        @greeting.(name)
-      end
-    end
-  end
-end
-
-Context.new.('Alice')
-# => [2, ["1. Hello Alice", "2. Hello Alice!"]]
-```
-
-Now the same code returns a different result! Even more, it has a different shape (or type, if you will): `((Integer, String), (Integer, String))` vs. `(Integer, (String, String))`!
-
-### Algebraic effects
-
-Algebraic effects are relatively recent research describing a possible implementation of the effect system. An effect is some capability your code requires to be executed. It gives control over what your code does and helps a lot with testing without involving any magic like `allow(Time).to receive(:now).and_return(@time_now)`. Instead, getting the current time is just another effect, as simple as that.
-
-Algebraic effects lean towards functional programming enabling things like dependency injection, mutable state, obtaining the current time and random values in pure code. All that is done avoiding troubles accompanying monad stacks and monad transformers. Even things like JavaScript's `async`/`await` and Python's `asyncio` can be generalized with algebraic effects.
-
-If you're interested in the subject, there is a list of articles, papers, and videos, in no particular order:
-
-- [Algebraic Effects for the Rest of Us](https://overreacted.io/algebraic-effects-for-the-rest-of-us/) by Dan Abramov, an (unsophisticated) introduction for React/JavaScript developers.
-- [An Introduction to Algebraic Effects and Handlers](https://www.eff-lang.org/handlers-tutorial.pdf) is an approachable paper describing the semantics. Take a look if you want to know more on the subject.
-- [Algebraic Effects for Functional Programming](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/08/algeff-tr-2016-v2.pdf) is another paper by Microsoft Research.
-- [Asynchrony with Algebraic Effects](https://www.youtube.com/watch?v=hrBq8R_kxI0) intro given by Daan Leijen, the author of the previous paper and the [Koka](https://github.com/koka-lang/koka) programming language created specifically for exploring algebraic effects.
-- [Do Be Do Be Do](https://arxiv.org/pdf/1611.09259.pdf) describes the Frank programming language with typed effects and ML-like syntax.
-
-### Goal of dry-effects
-
-Despite different effects are compatible one with each other, libraries implementing them (not using them!) are not compatible out of the box. `dry-effects` is aimed to be the standard implementation across dry-rb and rom-rb gems (and possibly others).