dry-effects 0.1.0 → 0.1.1

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

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

@@ -0,0 +1,42 @@
+---
+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/index.html.md

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

data/lib/dry/effects/extensions.rb

@@ -11,3 +11,7 @@ end
 Dry::Effects.register_extension(:system) do
   require 'dry/effects/extensions/system'
 end
+
+Dry::Effects.register_extension(:rspec) do
+  require 'dry/effects/extensions/rspec'
+end

data/lib/dry/effects/extensions/rspec.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# These patches make those rspec parts depending on Thread.current
+# play nice with dry-effects.
+# They've been used in production for months before been added here.
+
+RSpec::Support.singleton_class.prepend(Module.new {
+  include Dry::Effects.Reader(:rspec, as: :effect_local_data)
+
+  def thread_local_data
+    effect_local_data { super }
+  end
+})
+
+RSpec::Core::Runner.prepend(Module.new {
+  include Dry::Effects::Handler.Reader(:rspec, as: :run_with_data)
+
+  def run_specs(*)
+    run_with_data(RSpec::Support.thread_local_data) { super }
+  end
+})