State

State is a mutation effect. It allows reading and writing non-local values.

Basic usage

Handling code:

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:

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:

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:

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:

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:

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:

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:

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:

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.