39 - Ref: Mutable State, the Effect Way

Previous · Next

A Ref<A> is a mutable cell whose reads and writes are Effects. Updates are atomic across fibers, the value is invisible to outside code, and every operation composes like any other Effect, retries, interruption, and tests all work without special treatment.

What you’ll work through

index.test.ts covers Ref.make, Ref.get/Ref.set, the pure-update combinator Ref.update, and the read-and-update primitive Ref.modify, then finishes with a stateful service that hides the Ref behind a closure.

By the end you should be able to share state between concurrent fibers without losing updates, and know when a plain const would have been enough.

> `Ref`. Build it inside `Effect.gen`, never at module scope.

The Atomic Update Model

1
Ref<A>  is a box holding A.
2

3
  Ref.get      ──▶ Effect<A>           read the current value
4
  Ref.set      ──▶ Effect<void>        replace the value
5
  Ref.update   ──▶ Effect<void>        apply (a) => a
6
  Ref.modify   ──▶ Effect<B>           apply (a) => [b, a], return b
7

8
Atomicity: `update` / `modify` read-and-write in one step. Two concurrent
9
fibers calling `Ref.update(ref, n => n + 1)` will always agree on the
10
final value.

A plain let is invisible to the runtime: there is no atomic update, no interruption hook, no way to reset it for a test. Ref is.

`Ref.make`

Creates a new Ref holding the given value. The constructor is itself an Effect, so the Ref is produced inside Effect.gen, never at module scope.

1
import { Effect, Ref } from "effect"
2

3
//      ┌─── Effect<Ref<number>>
4
//      ▼
5
const makeCounter = Ref.make(0)

When to Use

Whenever you need state that changes during program execution and is observed by Effect code, counters, accumulators, caches, in-memory queues.

`Ref.get` and `Ref.set`

1
//      ┌─── Effect<number>
2
//      ▼
3
const program = Effect.gen(function* () {
4
  const ref = yield* Ref.make(0)
5
  yield* Ref.set(ref, 42)
6
  return yield* Ref.get(ref)
7
})

get snapshots the current value. set replaces it.

Neither operation reads the next value back, use Ref.modify when you need both.

`Ref.update`

Applies a function to the current value. The function must be pure: it runs inside the atomic compare-and-swap loop, possibly multiple times under contention.

1
//      ┌─── Effect<void>
2
//      ▼
3
const inc = (ref: Ref.Ref<number>) => Ref.update(ref, (n) => n + 1)

Details

For effectful updates ((A) => Effect<A>) reach for SynchronizedRef in step 40.

`Ref.modify`

The primitive atomic read-and-update. Returns a value computed from the old state while storing the new state.

1
//      ┌─── Effect<number>     (the old value)
2
//      ▼
3
const program = Effect.gen(function* () {
4
  const ref = yield* Ref.make(100)
5
  return yield* Ref.modify(ref, (n) => [n, n + 1])
6
  //                                 ▲   ▲
7
  //                                 │   └── new state
8
  //                                 └────── returned value
9
})

When to Use

Whenever a single fiber needs to read and decide in one indivisible step, dequeuing, issuing a sequence number, swapping a value while returning the old one.

1
//      ┌─── Effect<number>
2
//      ▼
3
const program = Effect.gen(function* () {
4
  const counter = yield* Ref.make(0)
5
  const increment = Ref.update(counter, (n) => n + 1)
6
  yield* Effect.all(Array.from({ length: 100 }, () => increment), {
7
    concurrency: "unbounded",
8
  })
9
  return yield* Ref.get(counter)
10
})
11
// 100, no lost updates

The same program written with a plain let and Effect.sync is a race waiting to happen.

A Stateful Service

1
//      ┌─── Effect<{ readonly increment: Effect<void>; readonly get: Effect<number> }>
2
//      ▼
3
const makeCounterService = Effect.gen(function* () {
4
  const ref = yield* Ref.make(0)
5
  return {
6
    increment: Ref.update(ref, (n) => n + 1),
7
    get: Ref.get(ref),
8
  } as const
9
})

The Ref is captured in the closure. Callers see only the operations; the state is encapsulated.

A concurrent stack from `Ref.modify`

Ref.modify atomically reads the current value and writes the next one in the same indivisible step. That’s the building block for any concurrent collection — a counter, a queue, a stack, a set.

The trick is keeping the function pure and returning both the new state and the value the caller wants.

1
import { Effect, Ref } from "effect"
2

3
const program = Effect.gen(function* () {
4
  const stack = yield* Ref.make<ReadonlyArray<number>>([])
5

6
  const push = (n: number) =>
7
    Ref.update(stack, (xs) => [n, ...xs])
8

9
  //      ┌─── Effect<number | undefined>
10
  //      ▼
11
  const pop = Ref.modify(stack, (xs) =>
12
    xs.length === 0
13
      ? [undefined, xs]               // [returned value, new state]
14
      : [xs[0], xs.slice(1)],
15
  )
16

17
  yield* Effect.all([push(1), push(2), push(3)], { concurrency: "unbounded" })
18
  return [yield* pop, yield* pop, yield* pop]
19
})

Even under concurrent push/pop, no two fibers ever see a torn state — modify is the atomic primitive that makes this safe without locks.

Your turn complete `pop` with `Ref.modify` so that read-and-write happen atomically; assert that under concurrent pushes the popped values are exactly the pushed ones (in some order).

Common Pitfalls

1, Using Ref.make at module scope. Ref.make(0) is Effect<Ref<number>>, not Ref<number>. You must yield* it inside an Effect.

2, Mutating inside the update function. The update function must be pure. Returning the same array after a .push breaks atomic semantics and can lose updates under contention.

1
// Wrong
2
Ref.update(ref, (arr) => { arr.push(item); return arr })
3
// Right
4
Ref.update(ref, (arr) => [...arr, item])

3, Using a Ref where the value never changes. If the value is computed once and never reassigned, use a plain const.

4, Reaching for Ref when the update needs to run an Effect. That is what SynchronizedRef (step 40) is for.

survives across `yield*` boundaries. - [ ] Use `Ref.update` with a pure function and prove that 100 concurrent increments produce exactly 100 — no lost updates. - [ ] Use `Ref.modify` to read-and-update in one atomic step (dequeue, issue a sequence number, swap-and-return). - [ ] Build the stateful counter service and confirm callers only see the operations, not the underlying `Ref`.

The full test suite

The index.test.ts for this lesson, verbatim from steps/39-ref/.

1
import { describe, it, expect } from "vite-plus/test"
2
import { Effect, Ref } from "effect"
3

4
// =============================================================================
5
// 35 - Ref: Mutable State, the Effect Way
6
// =============================================================================
7
//
8
// Ref.make    create a Ref<A>           — Effect<Ref<A>>
9
// Ref.get     read the current value    — Effect<A>
10
// Ref.set     replace the value         — Effect<void>
11
// Ref.update  apply (a) => a            — Effect<void>
12
// Ref.modify  apply (a) => [b, a]       — Effect<B>
13

14
describe("35 - Ref", () => {
15
  // @beat
16
  //   id: make-and-get
17
  //   shape: one-todo
18
  //   title: Create a Ref and read it back
19
  //   teaches: Ref.make is itself an Effect; yield* it to obtain a Ref, then Ref.get to read.
20
  //   hint: yield* Ref.make(0), then yield* Ref.get(ref)
21
  describe("Ref.make and Ref.get", () => {
22
    it("captures an initial value that can be read back", async () => {
23
      //      ┌─── Effect<number>
24
      //      ▼
25
      const program = /* @stub */ Effect.gen(function* () {
26
        const ref = yield* Ref.make(0)
27
        return yield* Ref.get(ref)
28
      }) /* @end */
29

30
      expect(await Effect.runPromise(program)).toBe(0)
31
    })
32
  })
33
  // @end-beat
34

35
  // @beat
36
  //   id: set
37
  //   shape: one-todo
38
  //   title: Replace the value with Ref.set
39
  //   teaches: Ref.set replaces the stored value; reads after a set observe the new value.
40
  //   hint: yield* Ref.set(ref, 42) then yield* Ref.get(ref)
41
  describe("Ref.set", () => {
42
    it("replaces the current value", async () => {
43
      const program = /* @stub */ Effect.gen(function* () {
44
        const ref = yield* Ref.make(0)
45
        yield* Ref.set(ref, 42)
46
        return yield* Ref.get(ref)
47
      }) /* @end */
48

49
      expect(await Effect.runPromise(program)).toBe(42)
50
    })
51
  })
52
  // @end-beat
53

54
  // @beat
55
  //   id: update
56
  //   shape: multi-todo
57
  //   title: Update with a pure function
58
  //   teaches: Ref.update applies (a) => a atomically; the function must be pure because it may re-run under contention.
59
  //   hint: Ref.update(ref, (n) => n + 5)
60
  describe("Ref.update", () => {
61
    it("applies a pure function to the current value", async () => {
62
      const program = /* @stub */ Effect.gen(function* () {
63
        const ref = yield* Ref.make(10)
64
        yield* Ref.update(ref, (n) => n + 5)
65
        return yield* Ref.get(ref)
66
      }) /* @end */
67

68
      expect(await Effect.runPromise(program)).toBe(15)
69
    })
70

71
    it("composes sequential updates", async () => {
72
      const program = /* @stub */ Effect.gen(function* () {
73
        const counter = yield* Ref.make(0)
74
        yield* Ref.update(counter, (n) => n + 1)
75
        yield* Ref.update(counter, (n) => n + 1)
76
        yield* Ref.update(counter, (n) => n - 1)
77
        return yield* Ref.get(counter)
78
      }) /* @end */
79

80
      expect(await Effect.runPromise(program)).toBe(1)
81
    })
82
  })
83
  // @end-beat
84

85
  // @beat
86
  //   id: modify
87
  //   shape: one-todo
88
  //   title: Read-and-update atomically with Ref.modify
89
  //   teaches: Ref.modify takes (a) => [b, a] and returns b — read and write happen in one indivisible step.
90
  //   hint: Ref.modify(ref, (n) => [n, n + 1]) — first element is returned, second is the new state
91
  describe("Ref.modify", () => {
92
    it("returns the old value while storing the new one — atomically", async () => {
93
      //      ┌─── Effect<{ old: number; current: number }>
94
      //      ▼
95
      const program = /* @stub */ Effect.gen(function* () {
96
        const ref = yield* Ref.make(100)
97
        const old = yield* Ref.modify(ref, (n) => [n, n + 1])
98
        const current = yield* Ref.get(ref)
99
        return { old, current }
100
      }) /* @end */
101

102
      const result = await Effect.runPromise(program)
103
      expect(result.old).toBe(100)
104
      expect(result.current).toBe(101)
105
    })
106
  })
107
  // @end-beat
108

109
  // @beat
110
  //   id: stateful-service
111
  //   shape: one-todo
112
  //   title: Hide a Ref inside a service
113
  //   teaches: Capture the Ref in a closure and expose only the operations callers should see.
114
  //   hint: return an object literal exposing { increment: Ref.update(...), get: Ref.get(...) }
115
  describe("Concurrent updates", () => {
116
    it("loses no updates under unbounded concurrency", async () => {
117
      const program = Effect.gen(function* () {
118
        const counter = yield* Ref.make(0)
119
        const increment = Ref.update(counter, (n) => n + 1)
120
        yield* Effect.all(Array.from({ length: 100 }, () => increment), {
121
          concurrency: "unbounded",
122
        })
123
        return yield* Ref.get(counter)
124
      })
125

126
      expect(await Effect.runPromise(program)).toBe(100)
127
    })
128
  })
129

130
  describe("Capturing state in a service", () => {
131
    it("exposes operations while hiding the Ref itself", async () => {
132
      const makeCounter = /* @stub */ Effect.gen(function* () {
133
        const ref = yield* Ref.make(0)
134
        return {
135
          increment: Ref.update(ref, (n) => n + 1),
136
          get: Ref.get(ref),
137
        } as const
138
      }) /* @end */
139

140
      const program = Effect.gen(function* () {
141
        const counter = yield* makeCounter
142
        yield* counter.increment
143
        yield* counter.increment
144
        return yield* counter.get
145
      })
146

147
      expect(await Effect.runPromise(program)).toBe(2)
148
    })
149
  })
150
  // @end-beat
151

152
  // @beat
153
  //   id: concurrent-stack
154
  //   shape: worked-then-your-turn
155
  //   title: Build a concurrent stack using Ref
156
  //   teaches: Ref.modify atomically reads the old value and stores the new one — the same pattern that makes a concurrent counter works for a concurrent stack.
157
  //   hint: Ref.modify(ref, (stack) => [stack[0], stack.slice(1)]) for pop — return [poppedValue, newStack]
158

159
  describe("Worked: concurrent counter", () => {
160
    it("uses Ref.update for an atomic increment", async () => {
161
      const program = Effect.gen(function* () {
162
        const counter = yield* Ref.make(0)
163
        yield* Effect.all(Array.from({ length: 10 }, () => Ref.update(counter, (n) => n + 1)), {
164
          concurrency: "unbounded",
165
        })
166
        return yield* Ref.get(counter)
167
      })
168

169
      expect(await Effect.runPromise(program)).toBe(10)
170
    })
171
  })
172

173
  describe("Your turn: concurrent stack", () => {
174
    it("push and pop from a Ref-backed stack atomically", async () => {
175
      //      ┌─── Effect<{ pushed: number[]; popped: number[] }>
176
      //      ▼
177
      const program = /* @stub */ Effect.gen(function* () {
178
        const stack = yield* Ref.make<number[]>([])
179

180
        // push: prepend to the array
181
        const push = (n: number) => Ref.update(stack, (s) => [n, ...s])
182
        // pop: return the head, store the tail — use Ref.modify
183
        const pop = Ref.modify(stack, (s) => [s[0] ?? -1, s.slice(1)])
184

185
        yield* push(1)
186
        yield* push(2)
187
        yield* push(3)
188

189
        const a = yield* pop
190
        const b = yield* pop
191

192
        return { remaining: yield* Ref.get(stack), popped: [a, b] }
193
      }) /* @end */
194

195
      const result = await Effect.runPromise(program)
196
      expect(result.popped).toEqual([3, 2]) // LIFO
197
      expect(result.remaining).toEqual([1])
198
    })
199
  })
200
  // @end-beat
201
})

07·01Ref

39 - Ref: Mutable State, the Effect Way

What you’ll work through

The Atomic Update Model

`Ref.make`

`Ref.get` and `Ref.set`

`Ref.update`

`Ref.modify`

A Stateful Service

A concurrent stack from `Ref.modify`

Common Pitfalls

See Also

The full test suite

07·01Ref

39 - Ref: Mutable State, the Effect Way

What you’ll work through

The Atomic Update Model

Ref.make

Ref.get and Ref.set

Ref.update

Ref.modify

Sharing State Across Fibers

A Stateful Service

A concurrent stack from Ref.modify

Common Pitfalls

See Also

The full test suite

`Ref.make`

`Ref.get` and `Ref.set`

`Ref.update`

`Ref.modify`

A concurrent stack from `Ref.modify`