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

4
// =============================================================================
5
// 02 - Description vs Execution
6
// =============================================================================
7
//
8
// A regular function runs when called. An Effect is a value that describes
9
// work; nothing happens until a runner executes it. This lesson makes the
10
// distinction observable.
11

12
// @beat
13
//   id: functions-run-immediately
14
//   shape: read-run
15
//   title: A function runs the moment you call it
16
//   teaches: Calling a regular function is the same act as running it; there is no "describe now, run later" for plain JS calls.
17
//   hint: each call to work() fires the side effect, so the counter equals the number of calls
18
it("a regular function call fires its side effect immediately", () => {
19
  let called = 0
20
  const work = () => {
21
    called++
22
  }
23

24
  work()
25
  work()
26

27
  expect(called).toBe(2)
28
})
29
// @end-beat
30

31
// @beat
32
//   id: effects-are-descriptions
33
//   shape: one-todo
34
//   title: Constructing an Effect does not run it
35
//   teaches: Effect.sync captures a function inside a value; the captured function is not invoked until a runner walks the description.
36
//   hint: the body of Effect.sync hasn't been executed yet — predict the counter
37
it("Effect.sync captures the work without running it", () => {
38
  let fired = 0
39

40
  const describeWork = Effect.sync(() => {
41
    fired++
42
  })
43

44
  // Predict the counter value before any runner has been applied.
45
  expect(fired).toBe(/* @stub */ 0 /* @end */)
46

47
  // The Effect value is still usable as a value (we can name it, return it, hand it around).
48
  expect(typeof describeWork).toBe("object")
49
})
50
// @end-beat
51

52
// @beat
53
//   id: runner-triggers-execution
54
//   shape: one-todo
55
//   title: A runner is what makes it happen
56
//   teaches: Runners (runSync, runPromise, runPromiseExit, runFork) are the only thing in Effect that performs the work captured by a description.
57
//   hint: Effect.runSync(describeWork) — and watch the counter move
58
it("Effect.runSync executes the described work", () => {
59
  let fired = 0
60
  const describeWork = Effect.sync(() => {
61
    fired++
62
  })
63

64
  /* @stub */ Effect.runSync(describeWork) /* @end */
65

66
  expect(fired).toBe(1)
67
})
68
// @end-beat
69

70
// @beat
71
//   id: descriptions-are-reusable
72
//   shape: one-todo
73
//   title: The same description can be run any number of times
74
//   teaches: An Effect value is immutable; each runner invocation produces a fresh execution. This is what makes retry and repeat free.
75
//   hint: call Effect.runSync(work) twice — the counter should reach 2
76
it("re-running a description produces a fresh execution each time", () => {
77
  let count = 0
78
  const work = Effect.sync(() => {
79
    count++
80
  })
81

82
  /* @stub */ Effect.runSync(work) /* @end */
83
  /* @stub */ Effect.runSync(work) /* @end */
84

85
  expect(count).toBe(2)
86
})
87
// @end-beat
88

89
// @beat
90
//   id: forgotten-runner
91
//   shape: mistake-first
92
//   title: The forgotten-runner bug
93
//   teaches: An Effect that is never handed to a runner is just an unused value. If your side effects never fire, look first for an Effect that was constructed but never run.
94
//   hint: the first assertion shows the bug; the second adds the runner and confirms the fix
95
it("an Effect that is never run does nothing — even though it was 'called'", () => {
96
  let saved = false
97
  const persist = Effect.sync(() => {
98
    saved = true
99
  })
100

101
  // ❌ Common mistake — Effect is created but never handed to a runner.
102
  persist
103

104
  expect(saved).toBe(false)
105

106
  // ✅ Fix — actually run it.
107
  /* @stub */ Effect.runSync(persist) /* @end */
108

109
  expect(saved).toBe(true)
110
})
111
// @end-beat
112

113
// @beat
114
//   id: composed-still-lazy
115
//   shape: multi-todo
116
//   title: Composed programs are still just descriptions
117
//   teaches: pipe and flatMap compose descriptions into larger descriptions; nothing runs until a runner is applied at the edge.
118
//   hint: predict the audit before any runner fires, then after both steps execute in order
119
it("composing Effects builds a larger description — still no execution", () => {
120
  const audit: Array<string> = []
121

122
  const program = Effect.sync(() => {
123
    audit.push("step-a")
124
  }).pipe(
125
    Effect.flatMap(() =>
126
      Effect.sync(() => {
127
        audit.push("step-b")
128
      }),
129
    ),
130
  )
131

132
  // Predict the audit array before the runner has touched the program.
133
  expect(audit).toEqual(/* @stub */ [] /* @end */)
134

135
  Effect.runSync(program)
136

137
  // Predict the audit array after the composed program runs to completion.
138
  expect(audit).toEqual(/* @stub */ ["step-a", "step-b"] /* @end */)
139
})
140
// @end-beat