An educational pure functional programming library in TypeScript
Add Forest Election story trilogy teaching Validation, Result, and Effects
+2069
+14
docs/guides/README.md
+14
docs/guides/README.md
···
17
17
18
18
Jump to the [Concepts](./concepts/) section for deep-dives into specific topics. Each article is self-contained and includes real-world examples.
19
19
20
+
### Prefer Learning Through Narrative?
21
+
22
+
Try the [Stories](./stories/) — whimsical tales where animal characters discover functional programming concepts by building real software. Each story is a gentle introduction that weaves code into narrative.
23
+
20
24
---
21
25
22
26
## [Tutorial](./tutorial/)
···
55
59
| [Fiber Internals](./concepts/07-fiber-internals.md) | How the runtime works under the hood |
56
60
| [Dependency Injection Patterns](./concepts/08-dependency-injection-patterns.md) | Testing, layered environments |
57
61
| [Testing Strategies](./concepts/09-testing-strategies.md) | Unit testing effectful code |
62
+
63
+
---
64
+
65
+
## [Stories](./stories/)
66
+
67
+
Learn through narrative — whimsical tales where animal characters discover FP concepts.
68
+
69
+
| Story | Concept | Description |
70
+
|--------------------------------------------------------------------|--------------------------|------------------------------------------------|
71
+
| [The Forest Election](./stories/forest-election/) | Validation, Result, Effects | Building a fair election system for the forest |
58
72
59
73
---
60
74
+45
docs/guides/stories/README.md
+45
docs/guides/stories/README.md
···
1
+
# Stories
2
+
3
+
**Stories** are narrative-driven functional programming tutorials. Each story is a whimsical tale where animal characters discover and build the same concepts you'll use in production code.
4
+
5
+
---
6
+
7
+
## Why Stories?
8
+
9
+
Traditional tutorials show you *what* to type. Stories show you *why* these patterns exist — through characters who face the same problems you do and discover the same solutions.
10
+
11
+
When Rabbit worries "But what if someone votes twice?", you feel the problem. When Owl scratches out a `BallotError` type, you understand why typed errors matter. The code isn't an afterthought; it's woven into the narrative as the characters write it.
12
+
13
+
---
14
+
15
+
## How to Read
16
+
17
+
1. **Follow the narrative** — Let the story carry you through the concepts
18
+
2. **Read the code** — Characters write real, runnable TypeScript
19
+
3. **Run the example** — Each story has a matching file in `examples/stories/`
20
+
4. **Try variations** — Modify the example to solidify your understanding
21
+
22
+
---
23
+
24
+
## Available Stories
25
+
26
+
### [The Forest Election](./forest-election/)
27
+
28
+
A trilogy about building a fair election system for the forest.
29
+
30
+
| Part | Title | Concept | Status |
31
+
|------|--------------------------------------------------------------------------|------------|-----------|
32
+
| 1 | [The Ballot Box Problem](./forest-election/01-the-ballot-box-problem.md) | Validation | Available |
33
+
| 2 | [Counting Day](./forest-election/02-counting-day.md) | Result | Available |
34
+
| 3 | [The Announcement](./forest-election/03-the-announcement.md) | Effects | Available |
35
+
36
+
**Tone:** Cozy and earnest (think Frog and Toad, Winnie the Pooh). The animals genuinely care about building fair software.
37
+
38
+
**Characters:** Owl (methodical thinker), Beaver (eager builder), Fox (pragmatic skeptic), Rabbit (anxious but thorough), Badger (wise elder).
39
+
40
+
---
41
+
42
+
## See Also
43
+
44
+
- [Tutorial](../tutorial/) — Step-by-step guide building a complete application
45
+
- [Concepts](../concepts/) — Deep-dive reference articles
+404
docs/guides/stories/forest-election/01-the-ballot-box-problem.md
+404
docs/guides/stories/forest-election/01-the-ballot-box-problem.md
···
1
+
# The Ballot Box Problem
2
+
3
+
*Part 1 of The Forest Election*
4
+
5
+
> In which the animals learn that finding ALL the problems
6
+
> is better than stopping at the first one.
7
+
8
+
---
9
+
10
+
The clearing was already crowded when Beaver arrived. Animals of every size had gathered beneath the ancient oak where forest business was conducted. Today was special — election day.
11
+
12
+
"Every five years," Badger was saying to a group of young hedgehogs, "we choose who speaks for the forest. It's how we've always done it."
13
+
14
+
Beaver pushed through to the front where the candidates stood: Deer, calm and diplomatic; Squirrel, practically vibrating with energy; and Heron, who said little but saw everything.
15
+
16
+
At the base of the oak sat the ballot box — really just a hollow log with a slit carved in the top. A pile of leaves waited beside it.
17
+
18
+
"The process is simple," Badger announced. "Write your name on a leaf, write your choice, place it in the box."
19
+
20
+
Fox leaned against a nearby tree, arms crossed. "Same as last time, then."
21
+
22
+
Something in his tone made Rabbit's ears twitch. "What happened last time?"
23
+
24
+
Badger sighed. "The Great Squirrel Dispute. Two squirrels claimed the same ballot. We couldn't tell who'd actually voted. It... did not end well."
25
+
26
+
---
27
+
28
+
The voting began. Animals scratched names on leaves and dropped them through the slit. Everything seemed orderly until Owl, who had been tasked with the count, tipped the box and began sorting.
29
+
30
+
"This one is blank," she said, setting a leaf aside. "No voter name."
31
+
32
+
"And this one..." She squinted. "The candidate says 'Wolfe.' We don't have a candidate named Wolfe."
33
+
34
+
"Maybe they meant Wolf?" suggested Beaver.
35
+
36
+
"Wolf isn't running either."
37
+
38
+
More leaves spilled out. Owl's pile of problems grew.
39
+
40
+
"Here's one from Rabbit, voting for Deer. And here's *another* one from Rabbit, also voting for Deer."
41
+
42
+
"I was nervous!" Rabbit squeaked. "I couldn't remember if I'd already voted!"
43
+
44
+
"And this one..." Owl turned the leaf over twice. "Has no candidate at all. Just a drawing of an acorn."
45
+
46
+
Fox pushed off from his tree. "Simple solution. Throw out the bad ones, count what's left."
47
+
48
+
"But then we don't know what went wrong!" Rabbit wrung her paws. "What if someone's vote was supposed to count but we rejected it? What if we could have *fixed* it?"
49
+
50
+
"Rabbit has a point," said Owl. "If we only stop at the first problem, we might miss others. Someone fixes their blank name, submits again, and *then* we tell them their candidate doesn't exist?"
51
+
52
+
"So what do you suggest?" Fox asked.
53
+
54
+
Owl smoothed a fresh leaf with her wing. "Let me show you something."
55
+
56
+
---
57
+
58
+
"A ballot," said Owl, scratching careful marks, "has structure. It's not just any leaf — it's a leaf with *requirements*."
59
+
60
+
```typescript
61
+
type Candidate = "Deer" | "Squirrel" | "Heron"
62
+
63
+
type Ballot = {
64
+
readonly voter: string
65
+
readonly candidate: Candidate
66
+
}
67
+
```
68
+
69
+
"A voter name," she continued. "And a candidate that must be one of our three."
70
+
71
+
Rabbit peered at the scratches. "But what happens when something's wrong?"
72
+
73
+
Owl made a new leaf. "Then we need to describe what's wrong. And there can be *multiple* things wrong with a single ballot."
74
+
75
+
```typescript
76
+
type BallotError =
77
+
| { readonly _tag: "MissingVoter" }
78
+
| { readonly _tag: "MissingCandidate" }
79
+
| { readonly _tag: "InvalidCandidate"; readonly name: string }
80
+
| { readonly _tag: "DuplicateVoter"; readonly voter: string }
81
+
```
82
+
83
+
"Missing voter," Rabbit said, reading along. "Missing candidate. Invalid candidate — that's the Wolfe one. And... duplicate voter." She looked sheepish.
84
+
85
+
"Now," said Owl, "the question is: when we find a problem, do we stop? Or do we keep looking?"
86
+
87
+
---
88
+
89
+
"Here's what most approaches do." Owl drew a diagram in the dirt.
90
+
91
+
```
92
+
Check voter → Check candidate → Valid ballot
93
+
↓ ↓
94
+
Stop Stop
95
+
(error) (error)
96
+
```
97
+
98
+
"If the voter is missing, we stop. We never check the candidate. The submitter fixes the voter, resubmits, *then* discovers the candidate problem."
99
+
100
+
"That's what Fox said," Beaver observed.
101
+
102
+
"And it's efficient," Fox said. "Why waste time checking more if it's already broken?"
103
+
104
+
"Because," Rabbit said quietly, "it's frustrating. You fix one thing, you find another. Fix that, find a third. How many trips back and forth?"
105
+
106
+
Owl nodded. "What if instead..."
107
+
108
+
```
109
+
Check voter ──────┐
110
+
│
111
+
Check candidate ──┼──→ Collect all problems
112
+
│
113
+
Check duplicate ──┘
114
+
```
115
+
116
+
"We check everything. Collect every problem. Report them all at once."
117
+
118
+
---
119
+
120
+
"In type terms," Owl continued, "this is the difference between `Result` and `Validation`."
121
+
122
+
She scratched new marks:
123
+
124
+
```typescript
125
+
// Result stops at the first error
126
+
// Validation collects ALL errors
127
+
128
+
import {
129
+
type Validation,
130
+
valid,
131
+
invalidOne,
132
+
apValidation,
133
+
matchValidation,
134
+
pipe,
135
+
} from "purus-ts"
136
+
```
137
+
138
+
"A `Validation` is either valid, containing a value, or invalid, containing a *list* of errors. Not one error — a list."
139
+
140
+
"Show us how it works," said Beaver.
141
+
142
+
---
143
+
144
+
Owl wrote the first validator:
145
+
146
+
```typescript
147
+
const validateVoter = (
148
+
voter: string | undefined
149
+
): Validation<string, BallotError> =>
150
+
voter && voter.trim().length > 0
151
+
? valid(voter.trim())
152
+
: invalidOne({ _tag: "MissingVoter" })
153
+
```
154
+
155
+
"If the voter exists and isn't blank, it's `valid`. Otherwise, `invalidOne` creates an invalid result with that single error."
156
+
157
+
"I could write one for candidates," Beaver offered.
158
+
159
+
"Please," said Owl.
160
+
161
+
Beaver took a leaf:
162
+
163
+
```typescript
164
+
const VALID_CANDIDATES: readonly Candidate[] = ["Deer", "Squirrel", "Heron"]
165
+
166
+
const validateCandidate = (
167
+
candidate: string | undefined
168
+
): Validation<Candidate, BallotError> =>
169
+
!candidate || candidate.trim().length === 0
170
+
? invalidOne({ _tag: "MissingCandidate" })
171
+
: VALID_CANDIDATES.includes(candidate as Candidate)
172
+
? valid(candidate as Candidate)
173
+
: invalidOne({ _tag: "InvalidCandidate", name: candidate })
174
+
```
175
+
176
+
"Good," said Owl. "If blank, missing. If not a valid candidate name, invalid. Otherwise, valid."
177
+
178
+
---
179
+
180
+
"But we have two validators," said Fox. "How do they become one?"
181
+
182
+
"This is where it gets interesting." Owl cleared a fresh patch of dirt. "We need to *combine* them. And the combining is what accumulates errors."
183
+
184
+
She wrote:
185
+
186
+
```typescript
187
+
const makeBallot =
188
+
(voter: string) =>
189
+
(candidate: Candidate): Ballot => ({
190
+
voter,
191
+
candidate,
192
+
})
193
+
194
+
const validateBallot = (
195
+
voter: string | undefined,
196
+
candidate: string | undefined
197
+
): Validation<Ballot, BallotError> =>
198
+
pipe(
199
+
valid(makeBallot),
200
+
apValidation(validateVoter(voter)),
201
+
apValidation(validateCandidate(candidate))
202
+
)
203
+
```
204
+
205
+
"Start with `valid(makeBallot)` — a validation containing a function that *builds* a ballot. Then `apValidation` applies each validator in turn."
206
+
207
+
"The magic," she tapped the leaf, "is what happens when things go wrong."
208
+
209
+
---
210
+
211
+
"Let me trace through." Owl made four columns:
212
+
213
+
```
214
+
Case 1: Both valid
215
+
valid(makeBallot) → Validation<(v) => (c) => Ballot>
216
+
ap(valid("Rabbit")) → Validation<(c) => Ballot>
217
+
ap(valid("Deer")) → Validation<Ballot>
218
+
Result: Valid({ voter: "Rabbit", candidate: "Deer" })
219
+
220
+
Case 2: Voter invalid
221
+
valid(makeBallot) → Validation<function>
222
+
ap(invalid([MissingVoter])) → Validation<function> with errors
223
+
ap(valid("Deer")) → still Invalid([MissingVoter])
224
+
Result: Invalid([MissingVoter])
225
+
226
+
Case 3: Both invalid
227
+
valid(makeBallot) → Validation<function>
228
+
ap(invalid([MissingVoter])) → Invalid([MissingVoter])
229
+
ap(invalid([MissingCand])) → Invalid([MissingVoter, MissingCand])
230
+
Result: Invalid([MissingVoter, MissingCandidate])
231
+
```
232
+
233
+
"In case 3, both errors are collected! That's accumulation."
234
+
235
+
Rabbit's eyes widened. "So we know *everything* that's wrong. All at once."
236
+
237
+
"Exactly."
238
+
239
+
---
240
+
241
+
Fox had been studying the scratches. "What about duplicates? Rabbit voted twice."
242
+
243
+
"We need to track who's voted." Owl thought for a moment. "That's state — we'll need to check against a list."
244
+
245
+
```typescript
246
+
const validateNoDuplicate = (
247
+
voter: string,
248
+
alreadyVoted: ReadonlySet<string>
249
+
): Validation<string, BallotError> =>
250
+
alreadyVoted.has(voter)
251
+
? invalidOne({ _tag: "DuplicateVoter", voter })
252
+
: valid(voter)
253
+
```
254
+
255
+
"And we can combine this with the others." She rewrote the full validator:
256
+
257
+
```typescript
258
+
const validateBallotFull = (
259
+
voter: string | undefined,
260
+
candidate: string | undefined,
261
+
alreadyVoted: ReadonlySet<string>
262
+
): Validation<Ballot, BallotError> =>
263
+
pipe(
264
+
valid(makeBallot),
265
+
apValidation(
266
+
pipe(
267
+
validateVoter(voter),
268
+
// Only check duplicate if voter exists
269
+
(v) =>
270
+
v._tag === "Valid"
271
+
? pipe(
272
+
validateNoDuplicate(v.value, alreadyVoted),
273
+
// Keep the voter value if no duplicate
274
+
(dup) => (dup._tag === "Valid" ? v : dup)
275
+
)
276
+
: v
277
+
)
278
+
),
279
+
apValidation(validateCandidate(candidate))
280
+
)
281
+
```
282
+
283
+
"Hmm," said Beaver. "That duplicate check is a bit tangled."
284
+
285
+
"It is," Owl admitted. "There's an alternative — run all validators independently and combine errors manually. For now, this works."
286
+
287
+
---
288
+
289
+
"Show us the full thing running," said Fox. "Prove it works."
290
+
291
+
Owl gathered her leaves:
292
+
293
+
```typescript
294
+
const formatError = (error: BallotError): string => {
295
+
switch (error._tag) {
296
+
case "MissingVoter":
297
+
return "Ballot is missing a voter name"
298
+
case "MissingCandidate":
299
+
return "Ballot is missing a candidate"
300
+
case "InvalidCandidate":
301
+
return `"${error.name}" is not a valid candidate`
302
+
case "DuplicateVoter":
303
+
return `${error.voter} has already voted`
304
+
}
305
+
}
306
+
307
+
// Test ballots
308
+
const ballots = [
309
+
{ voter: "Rabbit", candidate: "Deer" }, // Valid
310
+
{ voter: undefined, candidate: "Squirrel" }, // Missing voter
311
+
{ voter: "Fox", candidate: undefined }, // Missing candidate
312
+
{ voter: "Beaver", candidate: "Wolfe" }, // Invalid candidate
313
+
{ voter: undefined, candidate: undefined }, // Both missing!
314
+
{ voter: "Rabbit", candidate: "Heron" }, // Duplicate voter
315
+
]
316
+
317
+
const alreadyVoted = new Set<string>()
318
+
319
+
ballots.forEach(({ voter, candidate }, i) => {
320
+
const result = validateBallotFull(voter, candidate, alreadyVoted)
321
+
322
+
matchValidation(
323
+
(ballot) => {
324
+
console.log(`Ballot ${i + 1}: Valid - ${ballot.voter} votes for ${ballot.candidate}`)
325
+
alreadyVoted.add(ballot.voter)
326
+
},
327
+
(errors) => {
328
+
console.log(`Ballot ${i + 1}: Invalid`)
329
+
errors.forEach((e) => console.log(` - ${formatError(e)}`))
330
+
}
331
+
)(result)
332
+
})
333
+
```
334
+
335
+
Owl ran through the leaves. The results appeared in the dirt:
336
+
337
+
```
338
+
Ballot 1: Valid - Rabbit votes for Deer
339
+
Ballot 2: Invalid
340
+
- Ballot is missing a voter name
341
+
Ballot 3: Invalid
342
+
- Ballot is missing a candidate
343
+
Ballot 4: Invalid
344
+
- "Wolfe" is not a valid candidate
345
+
Ballot 5: Invalid
346
+
- Ballot is missing a voter name
347
+
- Ballot is missing a candidate
348
+
Ballot 6: Invalid
349
+
- Rabbit has already voted
350
+
```
351
+
352
+
"Ballot 5!" Beaver pointed excitedly. "Two errors at once!"
353
+
354
+
"That's the one that would have needed two trips in the old way," said Rabbit. "Fix the voter, submit, then find out about the candidate."
355
+
356
+
"Now they know everything immediately."
357
+
358
+
---
359
+
360
+
Fox nodded slowly. "I'll admit, this is better than I expected."
361
+
362
+
"It's not about complexity," said Owl. "It's about respect. Respect for whoever is submitting. Tell them everything wrong at once. Let them fix it all in one go."
363
+
364
+
Badger had been quiet, watching. Now he spoke. "We have valid ballots and invalid ones. The invalid ones are clearly marked. We can set them aside, ask those voters to try again with corrections."
365
+
366
+
"And the valid ones are *truly* valid," added Rabbit. "We know they have a real voter, a real candidate, and no duplicates."
367
+
368
+
The sun was lower now. The pile of leaves had been sorted — valid on one side, invalid on the other with their errors carefully noted.
369
+
370
+
"The validation is done," said Badger. "Tomorrow, we count. And counting," he added with a slight smile, "can also go wrong."
371
+
372
+
Owl began gathering her notes. "Then we'll need a different tool for that. But that's tomorrow's problem."
373
+
374
+
The animals dispersed as evening fell. The ballot box sat beneath the oak, its contents finally trustworthy.
375
+
376
+
---
377
+
378
+
## What We Learned
379
+
380
+
1. **Validation accumulates errors** — Unlike `Result` which stops at the first error, `Validation` collects all of them.
381
+
382
+
2. **Use `valid` and `invalidOne`** — Constructors for success and single-error failure cases.
383
+
384
+
3. **Combine with `apValidation`** — Apply validations to a curried constructor. Errors from all steps are merged.
385
+
386
+
4. **Handle with `matchValidation`** — Pattern match on the result to handle valid values or error lists.
387
+
388
+
5. **Typed errors are documentation** — `BallotError` with its `_tag` variants makes it clear exactly what can go wrong.
389
+
390
+
---
391
+
392
+
## Try It Yourself
393
+
394
+
The complete code from this story is available as a runnable example:
395
+
396
+
```bash
397
+
bun examples/stories/forest-election/01-validation.ts
398
+
```
399
+
400
+
Try modifying the test ballots to see different error combinations.
401
+
402
+
---
403
+
404
+
*Next: [Counting Day](./02-counting-day.md) (coming soon)*
+376
docs/guides/stories/forest-election/02-counting-day.md
+376
docs/guides/stories/forest-election/02-counting-day.md
···
1
+
# Counting Day
2
+
3
+
*Part 2 of The Forest Election*
4
+
5
+
> In which the animals learn that some operations must stop
6
+
> at the first sign of trouble.
7
+
8
+
---
9
+
10
+
Morning light filtered through the oak's branches. The animals gathered again, quieter now. Yesterday's chaos had been tamed — the validated ballots sat in one neat pile, each one guaranteed to have a real voter, a valid candidate, and no duplicates.
11
+
12
+
"Now we count," said Badger.
13
+
14
+
"Finally, the easy part," Fox said, settling onto a log.
15
+
16
+
Owl tilted her head. "Is it?"
17
+
18
+
---
19
+
20
+
Beaver had already begun sorting ballots into three piles — one for each candidate. Deer's pile. Squirrel's pile. Heron's pile.
21
+
22
+
"Twelve for Deer," he announced. "Nine for Squirrel. Seven for Heron."
23
+
24
+
"Twenty-eight total," said Rabbit, who had been counting ballots as they came out of the box.
25
+
26
+
Beaver paused. "I count twenty-eight in my piles too."
27
+
28
+
"So we agree," said Badger. "Good."
29
+
30
+
"Wait." Owl had been watching silently. "What if the totals hadn't matched?"
31
+
32
+
Fox shrugged. "Recount."
33
+
34
+
"But which count was wrong? The pile sort or the box count? And what if we'd already announced a result based on corrupted data?"
35
+
36
+
---
37
+
38
+
Rabbit's ears flattened. "You mean... the count could be wrong and we wouldn't know?"
39
+
40
+
"The validation caught problems with individual ballots," said Owl. "But the *counting process* can have its own problems. What if a ballot falls between the piles? What if someone miscounts? What if the box total doesn't match the pile totals?"
41
+
42
+
"Yesterday's lesson was about collecting all errors," Beaver said slowly. "But counting is different. If my pile total doesn't match the box total, I can't just... keep counting."
43
+
44
+
"Exactly." Owl smoothed a fresh leaf. "Some operations need to *stop* at the first error. Let me show you."
45
+
46
+
---
47
+
48
+
```typescript
49
+
import {
50
+
type Result,
51
+
ok,
52
+
err,
53
+
chainResult,
54
+
mapResult,
55
+
matchResult,
56
+
pipe,
57
+
} from "purus-ts"
58
+
```
59
+
60
+
"Yesterday we used `Validation` which accumulates errors. Today we use `Result` which stops at the first one."
61
+
62
+
```typescript
63
+
type Candidate = "Deer" | "Squirrel" | "Heron"
64
+
65
+
type Ballot = {
66
+
readonly voter: string
67
+
readonly candidate: Candidate
68
+
}
69
+
70
+
type CountError =
71
+
| { readonly _tag: "EmptyBallotBox" }
72
+
| { readonly _tag: "TotalMismatch"; readonly expected: number; readonly actual: number }
73
+
| { readonly _tag: "TieDetected"; readonly candidates: readonly Candidate[]; readonly votes: number }
74
+
```
75
+
76
+
"Three things can go wrong during counting," Owl explained. "The box might be empty. The totals might not match. Or we might have a tie."
77
+
78
+
---
79
+
80
+
"Let's start with the simplest operation," said Beaver. "Counting ballots for one candidate."
81
+
82
+
```typescript
83
+
type VoteCounts = {
84
+
readonly Deer: number
85
+
readonly Squirrel: number
86
+
readonly Heron: number
87
+
}
88
+
89
+
const countVotes = (ballots: readonly Ballot[]): VoteCounts =>
90
+
ballots.reduce<VoteCounts>(
91
+
(counts, ballot) => ({
92
+
...counts,
93
+
[ballot.candidate]: counts[ballot.candidate] + 1,
94
+
}),
95
+
{ Deer: 0, Squirrel: 0, Heron: 0 }
96
+
)
97
+
```
98
+
99
+
"That can't fail," Fox observed.
100
+
101
+
"Not by itself, no. But watch what happens when we combine steps."
102
+
103
+
---
104
+
105
+
Owl drew the counting process as a pipeline:
106
+
107
+
```
108
+
Check not empty → Count votes → Verify total → Find winner
109
+
↓ ↓ ↓ ↓
110
+
Err? (ok) Err? Err?
111
+
```
112
+
113
+
"Each step can fail. And unlike validation, if *any* step fails, we must stop."
114
+
115
+
```typescript
116
+
const ensureNotEmpty = (
117
+
ballots: readonly Ballot[]
118
+
): Result<readonly Ballot[], CountError> =>
119
+
ballots.length === 0
120
+
? err({ _tag: "EmptyBallotBox" })
121
+
: ok(ballots)
122
+
```
123
+
124
+
"First gate: are there ballots at all?"
125
+
126
+
---
127
+
128
+
```typescript
129
+
const verifyTotal = (
130
+
ballots: readonly Ballot[],
131
+
counts: VoteCounts
132
+
): Result<VoteCounts, CountError> => {
133
+
const summed = counts.Deer + counts.Squirrel + counts.Heron
134
+
return summed === ballots.length
135
+
? ok(counts)
136
+
: err({
137
+
_tag: "TotalMismatch",
138
+
expected: ballots.length,
139
+
actual: summed,
140
+
})
141
+
}
142
+
```
143
+
144
+
"Second gate: does the sum match? If someone miscounted, or a ballot got lost, this will catch it."
145
+
146
+
Rabbit looked relieved. "So we'll know immediately if something's wrong."
147
+
148
+
"That's the point. With `Result`, we don't continue with bad data."
149
+
150
+
---
151
+
152
+
"What about finding the winner?" asked Beaver.
153
+
154
+
"That can also fail — if there's a tie."
155
+
156
+
```typescript
157
+
const findWinner = (
158
+
counts: VoteCounts
159
+
): Result<{ winner: Candidate; votes: number }, CountError> => {
160
+
const entries: readonly [Candidate, number][] = [
161
+
["Deer", counts.Deer],
162
+
["Squirrel", counts.Squirrel],
163
+
["Heron", counts.Heron],
164
+
]
165
+
166
+
const maxVotes = Math.max(...entries.map(([, v]) => v))
167
+
const winners = entries.filter(([, v]) => v === maxVotes)
168
+
169
+
return winners.length > 1
170
+
? err({
171
+
_tag: "TieDetected",
172
+
candidates: winners.map(([c]) => c),
173
+
votes: maxVotes,
174
+
})
175
+
: ok({ winner: winners[0]![0], votes: maxVotes })
176
+
}
177
+
```
178
+
179
+
Fox leaned forward. "What happens in a tie? We can't just pick one."
180
+
181
+
"We fail with `TieDetected`. The forest will need a runoff or some other procedure. That's not our decision to make — we just report that we can't determine a single winner."
182
+
183
+
---
184
+
185
+
"Now," said Owl, "we chain them together. This is where `Result` shows its nature."
186
+
187
+
```typescript
188
+
const runElection = (
189
+
ballots: readonly Ballot[]
190
+
): Result<{ winner: Candidate; votes: number; total: number }, CountError> =>
191
+
pipe(
192
+
ensureNotEmpty(ballots),
193
+
chainResult((validBallots) => {
194
+
const counts = countVotes(validBallots)
195
+
return pipe(
196
+
verifyTotal(validBallots, counts),
197
+
chainResult((verifiedCounts) =>
198
+
pipe(
199
+
findWinner(verifiedCounts),
200
+
mapResult((result) => ({
201
+
...result,
202
+
total: validBallots.length,
203
+
}))
204
+
)
205
+
)
206
+
)
207
+
})
208
+
)
209
+
```
210
+
211
+
"Each `chainResult` says: if the previous step succeeded, do this next. If it failed, stop here and propagate the error."
212
+
213
+
---
214
+
215
+
Beaver traced through the code. "So if `ensureNotEmpty` fails..."
216
+
217
+
"We never count votes."
218
+
219
+
"And if `verifyTotal` fails..."
220
+
221
+
"We never look for a winner. The error from `verifyTotal` becomes the final result."
222
+
223
+
"That's very different from yesterday," Rabbit said. "Yesterday we wanted *all* the errors."
224
+
225
+
"Different problems, different tools." Owl nodded. "Validation is for independent checks — each field can be wrong in its own way. Result is for dependent operations — each step needs the previous one to succeed."
226
+
227
+
---
228
+
229
+
Fox had been thinking. "But what if I *want* to recover from an error? What if an empty ballot box just means 'no votes cast' rather than a failure?"
230
+
231
+
"Good question." Owl added another leaf.
232
+
233
+
```typescript
234
+
const runElectionWithDefault = (
235
+
ballots: readonly Ballot[]
236
+
): Result<{ winner: Candidate | null; votes: number; total: number }, CountError> =>
237
+
pipe(
238
+
runElection(ballots),
239
+
// Recover from EmptyBallotBox specifically
240
+
(result) =>
241
+
result._tag === "Err" && result.error._tag === "EmptyBallotBox"
242
+
? ok({ winner: null, votes: 0, total: 0 })
243
+
: result
244
+
)
245
+
```
246
+
247
+
"You can catch specific errors and provide defaults. Other errors still propagate."
248
+
249
+
---
250
+
251
+
"Let me show you why this matters," said Owl. "Watch what happens with bad data."
252
+
253
+
She wrote out test cases:
254
+
255
+
```typescript
256
+
const formatError = (error: CountError): string => {
257
+
switch (error._tag) {
258
+
case "EmptyBallotBox":
259
+
return "No ballots in the box"
260
+
case "TotalMismatch":
261
+
return `Count mismatch: expected ${error.expected}, got ${error.actual}`
262
+
case "TieDetected":
263
+
return `Tie between ${error.candidates.join(" and ")} with ${error.votes} votes each`
264
+
}
265
+
}
266
+
267
+
// Test 1: Normal election
268
+
const normalBallots: readonly Ballot[] = [
269
+
{ voter: "Rabbit", candidate: "Deer" },
270
+
{ voter: "Fox", candidate: "Deer" },
271
+
{ voter: "Beaver", candidate: "Squirrel" },
272
+
{ voter: "Badger", candidate: "Deer" },
273
+
{ voter: "Owl", candidate: "Heron" },
274
+
]
275
+
276
+
matchResult(
277
+
(result) => console.log(`Winner: ${result.winner} with ${result.votes}/${result.total} votes`),
278
+
(error) => console.log(`Error: ${formatError(error)}`)
279
+
)(runElection(normalBallots))
280
+
// Winner: Deer with 3/5 votes
281
+
```
282
+
283
+
"The happy path works as expected."
284
+
285
+
---
286
+
287
+
```typescript
288
+
// Test 2: Empty box
289
+
matchResult(
290
+
(result) => console.log(`Winner: ${result.winner}`),
291
+
(error) => console.log(`Error: ${formatError(error)}`)
292
+
)(runElection([]))
293
+
// Error: No ballots in the box
294
+
```
295
+
296
+
"With an empty box, we stop immediately. No counting, no winner-finding."
297
+
298
+
```typescript
299
+
// Test 3: Tie
300
+
const tieBallots: readonly Ballot[] = [
301
+
{ voter: "Rabbit", candidate: "Deer" },
302
+
{ voter: "Fox", candidate: "Squirrel" },
303
+
{ voter: "Beaver", candidate: "Deer" },
304
+
{ voter: "Badger", candidate: "Squirrel" },
305
+
]
306
+
307
+
matchResult(
308
+
(result) => console.log(`Winner: ${result.winner}`),
309
+
(error) => console.log(`Error: ${formatError(error)}`)
310
+
)(runElection(tieBallots))
311
+
// Error: Tie between Deer and Squirrel with 2 votes each
312
+
```
313
+
314
+
"A tie is detected and reported. We don't pretend there's a winner when there isn't."
315
+
316
+
---
317
+
318
+
The sun had climbed higher. The real ballots still waited in their pile.
319
+
320
+
"I think I understand," said Beaver. "Validation is for checking everything independently. Result is for steps that depend on each other."
321
+
322
+
"Yesterday: find ALL the problems with a ballot."
323
+
324
+
"Today: stop at the FIRST problem with the count."
325
+
326
+
Owl nodded approvingly. "Two tools, two purposes. Use the right one for the job."
327
+
328
+
---
329
+
330
+
Badger cleared his throat. "Shall we count the real ballots, then?"
331
+
332
+
With Owl's framework in place, Beaver sorted while Rabbit counted. The pile totals matched. No ties emerged.
333
+
334
+
"Deer," announced Badger, "with twelve votes."
335
+
336
+
A murmur of approval rippled through the clearing. Deer dipped their head gracefully.
337
+
338
+
"Now we announce," said Badger. "And we must tell every corner of the forest."
339
+
340
+
"The messenger birds," said Rabbit, her worry returning. "They're not always reliable."
341
+
342
+
Owl began gathering fresh leaves. "Then we'll need something more than Result. We'll need something that can handle time, failure, and retry."
343
+
344
+
"Tomorrow," said Badger. "Today, we celebrate a successful count."
345
+
346
+
But Owl was already thinking ahead. Some problems couldn't be solved with pure functions. Some problems needed *effects*.
347
+
348
+
---
349
+
350
+
## What We Learned
351
+
352
+
1. **Result short-circuits on the first error** — Unlike Validation which collects all errors, Result stops immediately when something goes wrong.
353
+
354
+
2. **Use `chainResult` to sequence dependent operations** — Each step runs only if the previous succeeded.
355
+
356
+
3. **Use `mapResult` to transform success values** — Like adding the total to our winner result.
357
+
358
+
4. **Errors propagate automatically** — Once something fails, subsequent `chainResult` calls are skipped.
359
+
360
+
5. **Different tools for different problems** — Validation for independent checks, Result for dependent operations.
361
+
362
+
---
363
+
364
+
## Try It Yourself
365
+
366
+
The complete code from this story is available as a runnable example:
367
+
368
+
```bash
369
+
bun examples/stories/forest-election/02-result.ts
370
+
```
371
+
372
+
Try adding a corrupted count scenario where the totals don't match.
373
+
374
+
---
375
+
376
+
*Next: [The Announcement](./03-the-announcement.md)*
+393
docs/guides/stories/forest-election/03-the-announcement.md
+393
docs/guides/stories/forest-election/03-the-announcement.md
···
1
+
# The Announcement
2
+
3
+
*Part 3 of The Forest Election*
4
+
5
+
> In which the animals learn that some things take time,
6
+
> can fail, and need to be tried again.
7
+
8
+
---
9
+
10
+
The celebration had quieted. Deer stood gracefully beneath the oak, the new president of the forest. But the work wasn't done.
11
+
12
+
"Every creature must know," said Badger. "The North Meadow, the East Stream, the South Thicket, the Western Pines. News must reach them all."
13
+
14
+
"The messenger birds," said Rabbit. Her worry had returned. "Remember last winter? Half the messages never arrived."
15
+
16
+
Fox nodded slowly. "Sparrow got distracted by seeds. Jay argued with a squirrel and forgot her message entirely. And Wren... Wren just got lost."
17
+
18
+
"We can't just send messages and hope," said Beaver. "We need to know if they arrived."
19
+
20
+
Owl had been listening. "This is a different kind of problem. Validation checked things instantly. Counting was sequential. But sending messages... that takes *time*. And things that take time can fail in ways that instant operations can't."
21
+
22
+
---
23
+
24
+
"Let me show you what I mean," said Owl. "With our validation and counting, we wrote functions that returned immediately. But a message to the North Meadow doesn't return immediately. The bird has to fly there, deliver the message, and fly back."
25
+
26
+
```typescript
27
+
import {
28
+
type Eff,
29
+
succeed,
30
+
fail,
31
+
sleep,
32
+
flatMap,
33
+
mapEff,
34
+
foldEff,
35
+
pipe,
36
+
runPromise,
37
+
race,
38
+
retry,
39
+
all,
40
+
fork,
41
+
join,
42
+
} from "purus-ts"
43
+
```
44
+
45
+
"These are *effects*. Unlike `Result` which is just data, an `Eff` is a description of something that will happen — later, when we run it."
46
+
47
+
---
48
+
49
+
"First, let's model our messengers and destinations."
50
+
51
+
```typescript
52
+
type Region = "North Meadow" | "East Stream" | "South Thicket" | "Western Pines"
53
+
54
+
type MessageError =
55
+
| { readonly _tag: "BirdDistracted"; readonly bird: string; readonly reason: string }
56
+
| { readonly _tag: "BirdLost"; readonly bird: string }
57
+
| { readonly _tag: "Timeout"; readonly region: Region }
58
+
59
+
type DeliveryResult = {
60
+
readonly region: Region
61
+
readonly deliveredBy: string
62
+
readonly confirmationTime: number
63
+
}
64
+
```
65
+
66
+
"A message can fail because the bird got distracted, got lost, or took too long."
67
+
68
+
---
69
+
70
+
Rabbit studied the types. "But how do we represent the actual sending?"
71
+
72
+
"With an effect that describes what might happen." Owl scratched carefully.
73
+
74
+
```typescript
75
+
const sendMessage = (
76
+
region: Region,
77
+
bird: string,
78
+
reliabilityPercent: number
79
+
): Eff<DeliveryResult, MessageError, unknown> =>
80
+
pipe(
81
+
// Simulate flight time (200-800ms)
82
+
sleep(200 + Math.random() * 600),
83
+
flatMap(() => {
84
+
const roll = Math.random() * 100
85
+
86
+
// Bird gets distracted
87
+
if (roll > reliabilityPercent) {
88
+
const distractions = ["seeds", "a shiny object", "another bird", "a warm breeze"]
89
+
return fail({
90
+
_tag: "BirdDistracted",
91
+
bird,
92
+
reason: distractions[Math.floor(Math.random() * distractions.length)]!,
93
+
})
94
+
}
95
+
96
+
// Bird gets lost (5% chance even for reliable birds)
97
+
if (roll > reliabilityPercent - 5) {
98
+
return fail({ _tag: "BirdLost", bird })
99
+
}
100
+
101
+
// Success!
102
+
return succeed({
103
+
region,
104
+
deliveredBy: bird,
105
+
confirmationTime: Date.now(),
106
+
})
107
+
})
108
+
)
109
+
```
110
+
111
+
"This doesn't send anything yet," Owl emphasized. "It's just a *description* of sending. Nothing happens until we run it."
112
+
113
+
---
114
+
115
+
"That seems odd," said Fox. "What's the point of describing instead of doing?"
116
+
117
+
"Watch." Owl drew a diagram in the dirt.
118
+
119
+
```
120
+
Promise (eager): Effect (lazy):
121
+
122
+
const p = fetch(url) const e = sendMessage(...)
123
+
// Already started! // Nothing happened yet
124
+
125
+
await p await runPromise(e)
126
+
// Just waiting // NOW it runs
127
+
```
128
+
129
+
"With a Promise, the moment you create it, the work begins. With an Effect, creation and execution are separate. That means we can *compose* effects before running them."
130
+
131
+
---
132
+
133
+
Beaver's eyes lit up. "So we could build up a complex plan, then run it all at once?"
134
+
135
+
"Exactly. And we can add things like timeout, retry, and running multiple effects at the same time — all before anything actually executes."
136
+
137
+
```typescript
138
+
// Add a timeout to any effect
139
+
const sendWithTimeout = (
140
+
region: Region,
141
+
bird: string,
142
+
reliability: number,
143
+
timeoutMs: number
144
+
): Eff<DeliveryResult | null, MessageError, unknown> =>
145
+
pipe(
146
+
race(
147
+
sendMessage(region, bird, reliability),
148
+
pipe(
149
+
sleep(timeoutMs),
150
+
mapEff((): DeliveryResult | null => null)
151
+
)
152
+
),
153
+
flatMap((result) =>
154
+
result === null
155
+
? fail({ _tag: "Timeout", region } as MessageError)
156
+
: succeed(result)
157
+
)
158
+
)
159
+
```
160
+
161
+
"This sends a message but gives up if it takes too long. The `race` runs both effects and takes whichever finishes first."
162
+
163
+
---
164
+
165
+
"But if a bird fails," said Rabbit, "shouldn't we try again?"
166
+
167
+
"We can." Owl added another layer.
168
+
169
+
```typescript
170
+
const sendWithRetry = (
171
+
region: Region,
172
+
bird: string,
173
+
reliability: number,
174
+
maxAttempts: number
175
+
): Eff<DeliveryResult, MessageError, unknown> =>
176
+
pipe(
177
+
sendMessage(region, bird, reliability),
178
+
retry(maxAttempts - 1) // retry N-1 times = N total attempts
179
+
)
180
+
```
181
+
182
+
"This tries the message multiple times. If the first attempt fails, it tries again, up to `maxAttempts` total."
183
+
184
+
---
185
+
186
+
"Now here's where it gets interesting," said Owl. "We have four regions to notify. We could send them one at a time..."
187
+
188
+
```typescript
189
+
// Sequential: slow but simple
190
+
const announceSequentially = (
191
+
message: string
192
+
): Eff<DeliveryResult[], MessageError, unknown> =>
193
+
pipe(
194
+
sendWithRetry("North Meadow", "Sparrow", 70, 3),
195
+
flatMap((north) =>
196
+
pipe(
197
+
sendWithRetry("East Stream", "Jay", 80, 3),
198
+
flatMap((east) =>
199
+
pipe(
200
+
sendWithRetry("South Thicket", "Wren", 60, 3),
201
+
flatMap((south) =>
202
+
pipe(
203
+
sendWithRetry("Western Pines", "Robin", 85, 3),
204
+
mapEff((west) => [north, east, south, west])
205
+
)
206
+
)
207
+
)
208
+
)
209
+
)
210
+
)
211
+
)
212
+
```
213
+
214
+
"But that's slow. Each bird waits for the previous one to return."
215
+
216
+
---
217
+
218
+
"We can send them all at once." Owl's eyes gleamed.
219
+
220
+
```typescript
221
+
const announceInParallel = (): Eff<readonly DeliveryResult[], MessageError, unknown> =>
222
+
all([
223
+
sendWithRetry("North Meadow", "Sparrow", 70, 3),
224
+
sendWithRetry("East Stream", "Jay", 80, 3),
225
+
sendWithRetry("South Thicket", "Wren", 60, 3),
226
+
sendWithRetry("Western Pines", "Robin", 85, 3),
227
+
])
228
+
```
229
+
230
+
"`all` runs every effect at the same time. All four birds fly out together."
231
+
232
+
"What if one fails?" asked Fox.
233
+
234
+
"Then `all` fails with that error. If you want to collect all results regardless of failure, you need to handle errors inside each effect."
235
+
236
+
---
237
+
238
+
"Let me show you a more resilient version," said Owl.
239
+
240
+
```typescript
241
+
type AnnouncementResult =
242
+
| { readonly _tag: "Delivered"; readonly result: DeliveryResult }
243
+
| { readonly _tag: "Failed"; readonly region: Region; readonly error: MessageError }
244
+
245
+
const sendAndCapture = (
246
+
region: Region,
247
+
bird: string,
248
+
reliability: number
249
+
): Eff<AnnouncementResult, never, unknown> =>
250
+
pipe(
251
+
sendWithRetry(region, bird, reliability, 3),
252
+
foldEff(
253
+
(error) => succeed({ _tag: "Failed" as const, region, error }),
254
+
(result) => succeed({ _tag: "Delivered" as const, result })
255
+
)
256
+
)
257
+
```
258
+
259
+
"`foldEff` handles both success and failure, converting failures into successful results that describe the failure. Now `all` will never fail — we collect all outcomes."
260
+
261
+
---
262
+
263
+
```typescript
264
+
const announceToAllRegions = (): Eff<readonly AnnouncementResult[], never, unknown> =>
265
+
all([
266
+
sendAndCapture("North Meadow", "Sparrow", 70),
267
+
sendAndCapture("East Stream", "Jay", 80),
268
+
sendAndCapture("South Thicket", "Wren", 60),
269
+
sendAndCapture("Western Pines", "Robin", 85),
270
+
])
271
+
```
272
+
273
+
Rabbit traced through the logic. "So even if Wren fails, we still hear back from everyone else?"
274
+
275
+
"Exactly. We get a complete picture: who succeeded, who failed, and why."
276
+
277
+
---
278
+
279
+
"But wait," said Beaver. "You said nothing runs until we call `runPromise`. When do we actually send the birds?"
280
+
281
+
"Only when we explicitly run the effect." Owl demonstrated.
282
+
283
+
```typescript
284
+
const main = async () => {
285
+
console.log("Sending announcement to all regions...")
286
+
287
+
const results = await runPromise(announceToAllRegions())
288
+
289
+
const delivered = results.filter((r): r is { _tag: "Delivered"; result: DeliveryResult } =>
290
+
r._tag === "Delivered"
291
+
)
292
+
const failed = results.filter((r): r is { _tag: "Failed"; region: Region; error: MessageError } =>
293
+
r._tag === "Failed"
294
+
)
295
+
296
+
console.log(`Delivered: ${delivered.length}/4`)
297
+
delivered.forEach((d) =>
298
+
console.log(` ✓ ${d.result.region} via ${d.result.deliveredBy}`)
299
+
)
300
+
301
+
console.log(`Failed: ${failed.length}/4`)
302
+
failed.forEach((f) =>
303
+
console.log(` ✗ ${f.region}: ${formatError(f.error)}`)
304
+
)
305
+
}
306
+
```
307
+
308
+
"The moment `runPromise` executes, all four birds take flight. The results come back as they complete."
309
+
310
+
---
311
+
312
+
Fox had been quiet, processing. "So the effect is like... a blueprint?"
313
+
314
+
"Yes." Owl nodded. "A Promise is a running computation. An Effect is a plan for computation. You can inspect it, transform it, combine it with others — all before anything happens."
315
+
316
+
"And retry, timeout, race — those are just transformations on the blueprint?"
317
+
318
+
"Exactly. `retry(3)` doesn't retry anything. It takes one blueprint and returns a new blueprint that says 'try this, and if it fails, try again up to 3 times.'"
319
+
320
+
---
321
+
322
+
The afternoon light was golden now. The messenger birds waited on their branches, ready but not yet launched.
323
+
324
+
"I understand now," said Rabbit. "Validation for independent checks. Result for dependent steps. Effects for things that take time and might fail."
325
+
326
+
"And effects compose," added Beaver. "Timeout, retry, parallel — we build them up piece by piece."
327
+
328
+
"Three tools for three kinds of problems," said Badger. "The forest is fortunate to have such careful builders."
329
+
330
+
---
331
+
332
+
Owl looked at the waiting birds. "Shall we send the announcement?"
333
+
334
+
Badger nodded.
335
+
336
+
Owl scratched one final mark — `runPromise(announceToAllRegions())` — and the birds took flight. Four shapes against the evening sky, carrying news to every corner of the forest.
337
+
338
+
Some would arrive quickly. Some might need a second try. But the plan was sound, the errors were handled, and the forest would know its new president.
339
+
340
+
*In the clearing beneath the ancient oak, the animals watched the birds disappear into the distance. The election was complete — validated, counted, and now announced. Deer stepped forward, ready to serve.*
341
+
342
+
*And somewhere in the machinery of the forest, effects were running, fibers were racing, and promises were being kept.*
343
+
344
+
---
345
+
346
+
## What We Learned
347
+
348
+
1. **Effects are descriptions, not actions** — An `Eff<A, E, R>` describes what might happen. Nothing runs until `runPromise`.
349
+
350
+
2. **Lazy evaluation enables composition** — Because effects are just data, we can transform them (retry, timeout, race) before running.
351
+
352
+
3. **`flatMap` chains sequential effects** — "Do this, then do that with the result."
353
+
354
+
4. **`all` runs effects in parallel** — All effects start at once; fails fast on first error.
355
+
356
+
5. **`foldEff` handles success and failure** — Convert failures to successes when you want to collect all results.
357
+
358
+
6. **`race` takes the first to complete** — Perfect for timeouts: race your effect against a sleep.
359
+
360
+
7. **`retry` automatically retries failures** — Wrap any effect with retry logic without changing the original code.
361
+
362
+
---
363
+
364
+
## Try It Yourself
365
+
366
+
The complete code from this story is available as a runnable example:
367
+
368
+
```bash
369
+
bun examples/stories/forest-election/03-effects.ts
370
+
```
371
+
372
+
Try adjusting the bird reliability percentages and watch how retry changes the outcomes.
373
+
374
+
---
375
+
376
+
*The End of The Forest Election*
377
+
378
+
---
379
+
380
+
## What's Next?
381
+
382
+
You've completed the Forest Election trilogy! You've learned:
383
+
384
+
- **Part 1:** Validation accumulates all errors (independent checks)
385
+
- **Part 2:** Result short-circuits on first error (dependent operations)
386
+
- **Part 3:** Effects describe async work with composition (time and failure)
387
+
388
+
To dive deeper into any of these concepts, see:
389
+
390
+
- [Validation and Error Accumulation](../../concepts/03-validation-and-error-accumulation.md)
391
+
- [Why Errors as Values?](../../concepts/01-errors-as-values.md)
392
+
- [Effect Composition](../../concepts/06-effect-composition.md)
393
+
- [Fiber Internals](../../concepts/07-fiber-internals.md)
+92
docs/guides/stories/forest-election/README.md
+92
docs/guides/stories/forest-election/README.md
···
1
+
# The Forest Election
2
+
3
+
A story in three parts about building a fair election system.
4
+
5
+
---
6
+
7
+
## The Story
8
+
9
+
Every five years, the forest elects a president. This year, the animals decide to build proper software instead of trusting leaves in a box. Along the way, they discover why functional programming makes systems more reliable.
10
+
11
+
---
12
+
13
+
## Characters
14
+
15
+
| Character | Personality | Role in the Code |
16
+
|-----------|-------------|------------------|
17
+
| **Owl** | Methodical, patient | Introduces types and validation |
18
+
| **Beaver** | Eager, practical | Learns why validation-first matters |
19
+
| **Fox** | Skeptical, pragmatic | Questions complexity, comes around when the simple way fails |
20
+
| **Rabbit** | Anxious, detail-oriented | Her worries become the error types |
21
+
| **Badger** | Wise, experienced | Remembers past disasters, provides motivation |
22
+
23
+
**Candidates:** Deer (calm, diplomatic), Squirrel (energetic, populist), Heron (quiet wisdom).
24
+
25
+
---
26
+
27
+
## Parts
28
+
29
+
### Part 1: [The Ballot Box Problem](./01-the-ballot-box-problem.md)
30
+
31
+
The animals gather to elect a president, but the old way — leaves in a box — leads to chaos. Blank ballots, invalid candidates, duplicate votes. Fox wants to throw out bad ballots; Rabbit insists they need to know *all* the problems. Owl introduces the Validation type.
32
+
33
+
**Concept:** Validation and error accumulation
34
+
35
+
**You'll learn:**
36
+
- Why `Result` short-circuits but `Validation` accumulates
37
+
- Building validators with `valid` and `invalidOne`
38
+
- Combining validators with `apValidation`
39
+
- Using `matchValidation` to handle outcomes
40
+
41
+
---
42
+
43
+
### Part 2: [Counting Day](./02-counting-day.md)
44
+
45
+
The ballots are validated, but counting brings new challenges. What if the count doesn't match? What if there's a tie? The animals discover that some operations must short-circuit — and `Result` is the right tool.
46
+
47
+
**Concept:** Result and short-circuit error handling
48
+
49
+
**You'll learn:**
50
+
- Why `Result` stops at the first error (unlike `Validation`)
51
+
- Chaining dependent operations with `chainResult`
52
+
- Transforming success values with `mapResult`
53
+
- When to use Result vs Validation
54
+
55
+
---
56
+
57
+
### Part 3: [The Announcement](./03-the-announcement.md)
58
+
59
+
The winner must be announced to every corner of the forest. But the messenger birds are unreliable — some might not return. The animals need effects that can be retried, raced, and cancelled.
60
+
61
+
**Concept:** Effects, fibers, and concurrency
62
+
63
+
**You'll learn:**
64
+
- Effects as descriptions vs execution
65
+
- Chaining async operations with `flatMap`
66
+
- Running effects in parallel with `all`
67
+
- Error recovery with `foldEff`
68
+
- Automatic retry with `retry`
69
+
70
+
---
71
+
72
+
## Running the Code
73
+
74
+
Each part has a matching example file:
75
+
76
+
```bash
77
+
# Part 1: Validation
78
+
bun examples/stories/forest-election/01-validation.ts
79
+
80
+
# Part 2: Result
81
+
bun examples/stories/forest-election/02-result.ts
82
+
83
+
# Part 3: Effects
84
+
bun examples/stories/forest-election/03-effects.ts
85
+
```
86
+
87
+
---
88
+
89
+
## See Also
90
+
91
+
- [Stories overview](../) — Other available stories
92
+
- [Validation and Error Accumulation](../../concepts/03-validation-and-error-accumulation.md) — Technical deep-dive
+206
examples/stories/forest-election/01-validation.ts
+206
examples/stories/forest-election/01-validation.ts
···
1
+
/**
2
+
* The Forest Election — Part 1: Validation
3
+
* ==========================================
4
+
*
5
+
* This example accompanies the story at:
6
+
* docs/guides/stories/forest-election/01-the-ballot-box-problem.md
7
+
*
8
+
* It demonstrates how Validation accumulates ALL errors rather than
9
+
* stopping at the first one — perfect for form validation, ballot
10
+
* checking, or any scenario where you want complete feedback.
11
+
*
12
+
* Run with: bun examples/stories/forest-election/01-validation.ts
13
+
*/
14
+
15
+
import {
16
+
type Validation,
17
+
valid,
18
+
invalidOne,
19
+
apValidation,
20
+
matchValidation,
21
+
pipe,
22
+
} from "../../../src/index"
23
+
24
+
// =============================================================================
25
+
// Domain Types
26
+
// =============================================================================
27
+
28
+
type Candidate = "Deer" | "Squirrel" | "Heron"
29
+
30
+
type Ballot = {
31
+
readonly voter: string
32
+
readonly candidate: Candidate
33
+
}
34
+
35
+
type BallotError =
36
+
| { readonly _tag: "MissingVoter" }
37
+
| { readonly _tag: "MissingCandidate" }
38
+
| { readonly _tag: "InvalidCandidate"; readonly name: string }
39
+
| { readonly _tag: "DuplicateVoter"; readonly voter: string }
40
+
41
+
// =============================================================================
42
+
// Validators
43
+
// =============================================================================
44
+
45
+
const VALID_CANDIDATES: readonly Candidate[] = ["Deer", "Squirrel", "Heron"]
46
+
47
+
/**
48
+
* Validate that a voter name is present and non-empty.
49
+
*/
50
+
const validateVoter = (
51
+
voter: string | undefined,
52
+
): Validation<string, BallotError> =>
53
+
voter && voter.trim().length > 0
54
+
? valid(voter.trim())
55
+
: invalidOne({ _tag: "MissingVoter" })
56
+
57
+
/**
58
+
* Validate that a candidate is present and one of the valid options.
59
+
*/
60
+
const validateCandidate = (
61
+
candidate: string | undefined,
62
+
): Validation<Candidate, BallotError> =>
63
+
!candidate || candidate.trim().length === 0
64
+
? invalidOne({ _tag: "MissingCandidate" })
65
+
: VALID_CANDIDATES.includes(candidate as Candidate)
66
+
? valid(candidate as Candidate)
67
+
: invalidOne({ _tag: "InvalidCandidate", name: candidate })
68
+
69
+
/**
70
+
* Validate that a voter hasn't already voted.
71
+
*/
72
+
const validateNoDuplicate = (
73
+
voter: string,
74
+
alreadyVoted: ReadonlySet<string>,
75
+
): Validation<string, BallotError> =>
76
+
alreadyVoted.has(voter)
77
+
? invalidOne({ _tag: "DuplicateVoter", voter })
78
+
: valid(voter)
79
+
80
+
// =============================================================================
81
+
// Combined Validator
82
+
// =============================================================================
83
+
84
+
/**
85
+
* Curried ballot constructor for use with apValidation.
86
+
*/
87
+
const makeBallot =
88
+
(voter: string) =>
89
+
(candidate: Candidate): Ballot => ({
90
+
voter,
91
+
candidate,
92
+
})
93
+
94
+
/**
95
+
* Validate a complete ballot, checking:
96
+
* - Voter is present
97
+
* - Voter hasn't voted before
98
+
* - Candidate is present and valid
99
+
*
100
+
* All errors are accumulated — you get the complete list of problems.
101
+
*/
102
+
const validateBallot = (
103
+
voter: string | undefined,
104
+
candidate: string | undefined,
105
+
alreadyVoted: ReadonlySet<string>,
106
+
): Validation<Ballot, BallotError> =>
107
+
pipe(
108
+
valid(makeBallot),
109
+
apValidation(
110
+
pipe(validateVoter(voter), (voterResult) =>
111
+
voterResult._tag === "Valid"
112
+
? pipe(
113
+
validateNoDuplicate(voterResult.value, alreadyVoted),
114
+
(dupResult) => (dupResult._tag === "Valid" ? voterResult : dupResult),
115
+
)
116
+
: voterResult,
117
+
),
118
+
),
119
+
apValidation(validateCandidate(candidate)),
120
+
)
121
+
122
+
// =============================================================================
123
+
// Error Formatting
124
+
// =============================================================================
125
+
126
+
const formatError = (error: BallotError): string => {
127
+
switch (error._tag) {
128
+
case "MissingVoter":
129
+
return "Ballot is missing a voter name"
130
+
case "MissingCandidate":
131
+
return "Ballot is missing a candidate"
132
+
case "InvalidCandidate":
133
+
return `"${error.name}" is not a valid candidate`
134
+
case "DuplicateVoter":
135
+
return `${error.voter} has already voted`
136
+
}
137
+
}
138
+
139
+
// =============================================================================
140
+
// Demo
141
+
// =============================================================================
142
+
143
+
console.log("=== The Forest Election: Ballot Validation ===\n")
144
+
145
+
const testBallots: Array<{
146
+
voter: string | undefined
147
+
candidate: string | undefined
148
+
}> = [
149
+
{ voter: "Rabbit", candidate: "Deer" }, // Valid
150
+
{ voter: undefined, candidate: "Squirrel" }, // Missing voter
151
+
{ voter: "Fox", candidate: undefined }, // Missing candidate
152
+
{ voter: "Beaver", candidate: "Wolfe" }, // Invalid candidate
153
+
{ voter: undefined, candidate: undefined }, // Both missing!
154
+
{ voter: "Rabbit", candidate: "Heron" }, // Duplicate voter
155
+
{ voter: "Badger", candidate: "Deer" }, // Valid
156
+
{ voter: " ", candidate: "Squirrel" }, // Blank voter (whitespace)
157
+
{ voter: "Owl", candidate: "Eagle" }, // Invalid candidate
158
+
]
159
+
160
+
const alreadyVoted = new Set<string>()
161
+
const validBallots: Ballot[] = []
162
+
const invalidBallots: Array<{
163
+
index: number
164
+
errors: readonly BallotError[]
165
+
}> = []
166
+
167
+
console.log("Processing ballots...\n")
168
+
169
+
testBallots.forEach(({ voter, candidate }, i) => {
170
+
const result = validateBallot(voter, candidate, alreadyVoted)
171
+
172
+
matchValidation(
173
+
(ballot: Ballot) => {
174
+
console.log(
175
+
`Ballot ${i + 1}: Valid - ${ballot.voter} votes for ${ballot.candidate}`,
176
+
)
177
+
alreadyVoted.add(ballot.voter)
178
+
validBallots.push(ballot)
179
+
},
180
+
(errors: readonly BallotError[]) => {
181
+
console.log(`Ballot ${i + 1}: Invalid`)
182
+
errors.forEach((e) => console.log(` - ${formatError(e)}`))
183
+
invalidBallots.push({ index: i + 1, errors })
184
+
},
185
+
)(result)
186
+
})
187
+
188
+
// Summary
189
+
console.log("\n" + "=".repeat(50))
190
+
console.log("Summary")
191
+
console.log("=".repeat(50))
192
+
console.log(`Valid ballots: ${validBallots.length}`)
193
+
console.log(`Invalid ballots: ${invalidBallots.length}`)
194
+
195
+
console.log("\nVoters who cast valid ballots:")
196
+
validBallots.forEach((b) => console.log(` - ${b.voter} → ${b.candidate}`))
197
+
198
+
console.log("\nBallots with multiple errors:")
199
+
invalidBallots
200
+
.filter((b) => b.errors.length > 1)
201
+
.forEach((b) => {
202
+
console.log(` Ballot ${b.index}: ${b.errors.length} errors`)
203
+
})
204
+
205
+
console.log("\n=== End of validation phase ===")
206
+
console.log("Tomorrow, we count. And counting can also go wrong...")
+276
examples/stories/forest-election/02-result.ts
+276
examples/stories/forest-election/02-result.ts
···
1
+
/**
2
+
* The Forest Election — Part 2: Result
3
+
* =====================================
4
+
*
5
+
* This example accompanies the story at:
6
+
* docs/guides/stories/forest-election/02-counting-day.md
7
+
*
8
+
* It demonstrates how Result short-circuits on the first error —
9
+
* perfect for dependent operations where each step needs the
10
+
* previous one to succeed before continuing.
11
+
*
12
+
* Run with: bun examples/stories/forest-election/02-result.ts
13
+
*/
14
+
15
+
import {
16
+
type Result,
17
+
ok,
18
+
err,
19
+
chainResult,
20
+
mapResult,
21
+
matchResult,
22
+
pipe,
23
+
} from "../../../src/index"
24
+
25
+
// =============================================================================
26
+
// Domain Types
27
+
// =============================================================================
28
+
29
+
type Candidate = "Deer" | "Squirrel" | "Heron"
30
+
31
+
type Ballot = {
32
+
readonly voter: string
33
+
readonly candidate: Candidate
34
+
}
35
+
36
+
type CountError =
37
+
| { readonly _tag: "EmptyBallotBox" }
38
+
| {
39
+
readonly _tag: "TotalMismatch"
40
+
readonly expected: number
41
+
readonly actual: number
42
+
}
43
+
| {
44
+
readonly _tag: "TieDetected"
45
+
readonly candidates: readonly Candidate[]
46
+
readonly votes: number
47
+
}
48
+
49
+
type VoteCounts = {
50
+
readonly Deer: number
51
+
readonly Squirrel: number
52
+
readonly Heron: number
53
+
}
54
+
55
+
// =============================================================================
56
+
// Counting Functions
57
+
// =============================================================================
58
+
59
+
/**
60
+
* Count votes for each candidate.
61
+
* This operation cannot fail — it's pure transformation.
62
+
*/
63
+
const countVotes = (ballots: readonly Ballot[]): VoteCounts =>
64
+
ballots.reduce<VoteCounts>(
65
+
(counts, ballot) => ({
66
+
...counts,
67
+
[ballot.candidate]: counts[ballot.candidate] + 1,
68
+
}),
69
+
{ Deer: 0, Squirrel: 0, Heron: 0 },
70
+
)
71
+
72
+
/**
73
+
* Ensure the ballot box is not empty.
74
+
* First gate in our pipeline.
75
+
*/
76
+
const ensureNotEmpty = (
77
+
ballots: readonly Ballot[],
78
+
): Result<readonly Ballot[], CountError> =>
79
+
ballots.length === 0 ? err({ _tag: "EmptyBallotBox" }) : ok(ballots)
80
+
81
+
/**
82
+
* Verify that the counted votes match the number of ballots.
83
+
* Catches miscounts or lost ballots.
84
+
*/
85
+
const verifyTotal = (
86
+
ballots: readonly Ballot[],
87
+
counts: VoteCounts,
88
+
): Result<VoteCounts, CountError> => {
89
+
const summed = counts.Deer + counts.Squirrel + counts.Heron
90
+
return summed === ballots.length
91
+
? ok(counts)
92
+
: err({
93
+
_tag: "TotalMismatch",
94
+
expected: ballots.length,
95
+
actual: summed,
96
+
})
97
+
}
98
+
99
+
/**
100
+
* Find the winner from the vote counts.
101
+
* Fails if there's a tie.
102
+
*/
103
+
const findWinner = (
104
+
counts: VoteCounts,
105
+
): Result<{ winner: Candidate; votes: number }, CountError> => {
106
+
const entries: readonly [Candidate, number][] = [
107
+
["Deer", counts.Deer],
108
+
["Squirrel", counts.Squirrel],
109
+
["Heron", counts.Heron],
110
+
]
111
+
112
+
const maxVotes = Math.max(...entries.map(([, v]) => v))
113
+
const winners = entries.filter(([, v]) => v === maxVotes)
114
+
115
+
return winners.length > 1
116
+
? err({
117
+
_tag: "TieDetected",
118
+
candidates: winners.map(([c]) => c),
119
+
votes: maxVotes,
120
+
})
121
+
: ok({ winner: winners[0]![0], votes: maxVotes })
122
+
}
123
+
124
+
// =============================================================================
125
+
// Election Pipeline
126
+
// =============================================================================
127
+
128
+
/**
129
+
* Run the complete election count.
130
+
*
131
+
* Chain of dependent operations:
132
+
* 1. Check ballots exist
133
+
* 2. Count votes
134
+
* 3. Verify totals match
135
+
* 4. Find winner
136
+
*
137
+
* If ANY step fails, we stop immediately and return that error.
138
+
*/
139
+
const runElection = (
140
+
ballots: readonly Ballot[],
141
+
): Result<{ winner: Candidate; votes: number; total: number }, CountError> =>
142
+
pipe(
143
+
ensureNotEmpty(ballots),
144
+
chainResult((validBallots) => {
145
+
const counts = countVotes(validBallots)
146
+
return pipe(
147
+
verifyTotal(validBallots, counts),
148
+
chainResult((verifiedCounts) =>
149
+
pipe(
150
+
findWinner(verifiedCounts),
151
+
mapResult((result) => ({
152
+
...result,
153
+
total: validBallots.length,
154
+
})),
155
+
),
156
+
),
157
+
)
158
+
}),
159
+
)
160
+
161
+
// =============================================================================
162
+
// Error Formatting
163
+
// =============================================================================
164
+
165
+
const formatError = (error: CountError): string => {
166
+
switch (error._tag) {
167
+
case "EmptyBallotBox":
168
+
return "No ballots in the box"
169
+
case "TotalMismatch":
170
+
return `Count mismatch: expected ${error.expected}, got ${error.actual}`
171
+
case "TieDetected":
172
+
return `Tie between ${error.candidates.join(" and ")} with ${error.votes} votes each`
173
+
}
174
+
}
175
+
176
+
// =============================================================================
177
+
// Demo
178
+
// =============================================================================
179
+
180
+
console.log("=== The Forest Election: Counting Day ===\n")
181
+
182
+
// Test 1: Normal election with clear winner
183
+
console.log("--- Test 1: Normal election ---")
184
+
const normalBallots: readonly Ballot[] = [
185
+
{ voter: "Rabbit", candidate: "Deer" },
186
+
{ voter: "Fox", candidate: "Deer" },
187
+
{ voter: "Beaver", candidate: "Squirrel" },
188
+
{ voter: "Badger", candidate: "Deer" },
189
+
{ voter: "Owl", candidate: "Heron" },
190
+
{ voter: "Hedgehog", candidate: "Deer" },
191
+
{ voter: "Mole", candidate: "Squirrel" },
192
+
]
193
+
194
+
matchResult(
195
+
(result) =>
196
+
console.log(
197
+
`Winner: ${result.winner} with ${result.votes}/${result.total} votes`,
198
+
),
199
+
(error) => console.log(`Error: ${formatError(error)}`),
200
+
)(runElection(normalBallots))
201
+
console.log()
202
+
203
+
// Test 2: Empty ballot box
204
+
console.log("--- Test 2: Empty ballot box ---")
205
+
matchResult(
206
+
(result) => console.log(`Winner: ${result.winner}`),
207
+
(error) => console.log(`Error: ${formatError(error)}`),
208
+
)(runElection([]))
209
+
console.log()
210
+
211
+
// Test 3: Two-way tie
212
+
console.log("--- Test 3: Two-way tie ---")
213
+
const twoWayTie: readonly Ballot[] = [
214
+
{ voter: "Rabbit", candidate: "Deer" },
215
+
{ voter: "Fox", candidate: "Squirrel" },
216
+
{ voter: "Beaver", candidate: "Deer" },
217
+
{ voter: "Badger", candidate: "Squirrel" },
218
+
]
219
+
matchResult(
220
+
(result) => console.log(`Winner: ${result.winner}`),
221
+
(error) => console.log(`Error: ${formatError(error)}`),
222
+
)(runElection(twoWayTie))
223
+
console.log()
224
+
225
+
// Test 4: Three-way tie
226
+
console.log("--- Test 4: Three-way tie ---")
227
+
const threeWayTie: readonly Ballot[] = [
228
+
{ voter: "Rabbit", candidate: "Deer" },
229
+
{ voter: "Fox", candidate: "Squirrel" },
230
+
{ voter: "Beaver", candidate: "Heron" },
231
+
]
232
+
matchResult(
233
+
(result) => console.log(`Winner: ${result.winner}`),
234
+
(error) => console.log(`Error: ${formatError(error)}`),
235
+
)(runElection(threeWayTie))
236
+
console.log()
237
+
238
+
// Test 5: Larger election
239
+
console.log("--- Test 5: Full forest election ---")
240
+
const fullElection: readonly Ballot[] = [
241
+
// Deer voters
242
+
{ voter: "Rabbit", candidate: "Deer" },
243
+
{ voter: "Mouse", candidate: "Deer" },
244
+
{ voter: "Chipmunk", candidate: "Deer" },
245
+
{ voter: "Turtle", candidate: "Deer" },
246
+
{ voter: "Frog", candidate: "Deer" },
247
+
// Squirrel voters
248
+
{ voter: "Fox", candidate: "Squirrel" },
249
+
{ voter: "Weasel", candidate: "Squirrel" },
250
+
{ voter: "Raccoon", candidate: "Squirrel" },
251
+
{ voter: "Possum", candidate: "Squirrel" },
252
+
// Heron voters
253
+
{ voter: "Owl", candidate: "Heron" },
254
+
{ voter: "Crane", candidate: "Heron" },
255
+
{ voter: "Duck", candidate: "Heron" },
256
+
]
257
+
258
+
const result = runElection(fullElection)
259
+
matchResult(
260
+
(r) => {
261
+
console.log(`Winner: ${r.winner}`)
262
+
console.log(`Votes: ${r.votes} out of ${r.total}`)
263
+
console.log(`Percentage: ${((r.votes / r.total) * 100).toFixed(1)}%`)
264
+
},
265
+
(error) => console.log(`Error: ${formatError(error)}`),
266
+
)(result)
267
+
268
+
// Show the counts
269
+
const counts = countVotes(fullElection)
270
+
console.log("\nVote breakdown:")
271
+
console.log(` Deer: ${counts.Deer}`)
272
+
console.log(` Squirrel: ${counts.Squirrel}`)
273
+
console.log(` Heron: ${counts.Heron}`)
274
+
275
+
console.log("\n=== Counting complete ===")
276
+
console.log("Tomorrow, we must announce the results to every corner of the forest...")
+263
examples/stories/forest-election/03-effects.ts
+263
examples/stories/forest-election/03-effects.ts
···
1
+
/**
2
+
* The Forest Election — Part 3: Effects
3
+
* =======================================
4
+
*
5
+
* This example accompanies the story at:
6
+
* docs/guides/stories/forest-election/03-the-announcement.md
7
+
*
8
+
* It demonstrates the Effect system — lazy, composable descriptions
9
+
* of async operations with built-in support for retry, timeout,
10
+
* parallel execution, and error handling.
11
+
*
12
+
* Run with: bun examples/stories/forest-election/03-effects.ts
13
+
*/
14
+
15
+
import {
16
+
type Eff,
17
+
succeed,
18
+
fail,
19
+
sleep,
20
+
flatMap,
21
+
mapEff,
22
+
foldEff,
23
+
pipe,
24
+
runPromise,
25
+
retry,
26
+
all,
27
+
} from "../../../src/index"
28
+
29
+
// =============================================================================
30
+
// Domain Types
31
+
// =============================================================================
32
+
33
+
type Region = "North Meadow" | "East Stream" | "South Thicket" | "Western Pines"
34
+
35
+
type MessageError =
36
+
| {
37
+
readonly _tag: "BirdDistracted"
38
+
readonly bird: string
39
+
readonly reason: string
40
+
}
41
+
| { readonly _tag: "BirdLost"; readonly bird: string }
42
+
| { readonly _tag: "Timeout"; readonly region: Region }
43
+
44
+
type DeliveryResult = {
45
+
readonly region: Region
46
+
readonly deliveredBy: string
47
+
readonly confirmationTime: number
48
+
}
49
+
50
+
type AnnouncementResult =
51
+
| { readonly _tag: "Delivered"; readonly result: DeliveryResult }
52
+
| {
53
+
readonly _tag: "Failed"
54
+
readonly region: Region
55
+
readonly error: MessageError
56
+
}
57
+
58
+
// =============================================================================
59
+
// Messenger Effects
60
+
// =============================================================================
61
+
62
+
const DISTRACTIONS = [
63
+
"seeds",
64
+
"a shiny object",
65
+
"another bird",
66
+
"a warm breeze",
67
+
"an interesting cloud",
68
+
]
69
+
70
+
/**
71
+
* Send a message to a region via a messenger bird.
72
+
*
73
+
* This is an EFFECT — it describes what might happen but doesn't
74
+
* execute until runPromise is called. The bird has a reliability
75
+
* percentage that determines success rate.
76
+
*/
77
+
const sendMessage = (
78
+
region: Region,
79
+
bird: string,
80
+
reliabilityPercent: number,
81
+
): Eff<DeliveryResult, MessageError, unknown> =>
82
+
pipe(
83
+
// Simulate flight time (200-800ms)
84
+
sleep(200 + Math.random() * 600),
85
+
flatMap(() => {
86
+
const roll = Math.random() * 100
87
+
88
+
// Bird gets distracted
89
+
if (roll > reliabilityPercent) {
90
+
const reason =
91
+
DISTRACTIONS[Math.floor(Math.random() * DISTRACTIONS.length)]!
92
+
return fail({
93
+
_tag: "BirdDistracted",
94
+
bird,
95
+
reason,
96
+
} as MessageError)
97
+
}
98
+
99
+
// Bird gets lost (5% chance even for reliable birds)
100
+
if (roll > reliabilityPercent - 5) {
101
+
return fail({ _tag: "BirdLost", bird } as MessageError)
102
+
}
103
+
104
+
// Success!
105
+
return succeed({
106
+
region,
107
+
deliveredBy: bird,
108
+
confirmationTime: Date.now(),
109
+
})
110
+
}),
111
+
)
112
+
113
+
/**
114
+
* Send a message with automatic retry on failure.
115
+
*
116
+
* The retry combinator wraps the effect — it doesn't change the
117
+
* original, it creates a new effect that will retry on failure.
118
+
*/
119
+
const sendWithRetry = (
120
+
region: Region,
121
+
bird: string,
122
+
reliability: number,
123
+
maxAttempts: number,
124
+
): Eff<DeliveryResult, MessageError, unknown> =>
125
+
pipe(sendMessage(region, bird, reliability), retry(maxAttempts - 1))
126
+
127
+
/**
128
+
* Send a message and capture the outcome as a success.
129
+
*
130
+
* foldEff converts failures into successes, so we can collect
131
+
* all results even when some birds fail.
132
+
*/
133
+
const sendAndCapture = (
134
+
region: Region,
135
+
bird: string,
136
+
reliability: number,
137
+
): Eff<AnnouncementResult, never, unknown> =>
138
+
pipe(
139
+
sendWithRetry(region, bird, reliability, 3),
140
+
foldEff(
141
+
(error) => succeed({ _tag: "Failed" as const, region, error }),
142
+
(result) => succeed({ _tag: "Delivered" as const, result }),
143
+
),
144
+
)
145
+
146
+
// =============================================================================
147
+
// Announcement Strategy
148
+
// =============================================================================
149
+
150
+
/**
151
+
* Announce to all four regions in parallel.
152
+
*
153
+
* all() runs every effect concurrently. Because we use sendAndCapture,
154
+
* individual failures don't stop other deliveries.
155
+
*/
156
+
const announceToAllRegions = (): Eff<
157
+
readonly AnnouncementResult[],
158
+
never,
159
+
unknown
160
+
> =>
161
+
all([
162
+
sendAndCapture("North Meadow", "Sparrow", 70),
163
+
sendAndCapture("East Stream", "Jay", 80),
164
+
sendAndCapture("South Thicket", "Wren", 60),
165
+
sendAndCapture("Western Pines", "Robin", 85),
166
+
])
167
+
168
+
// =============================================================================
169
+
// Error Formatting
170
+
// =============================================================================
171
+
172
+
const formatError = (error: MessageError): string => {
173
+
switch (error._tag) {
174
+
case "BirdDistracted":
175
+
return `${error.bird} got distracted by ${error.reason}`
176
+
case "BirdLost":
177
+
return `${error.bird} got lost`
178
+
case "Timeout":
179
+
return `Message to ${error.region} timed out`
180
+
}
181
+
}
182
+
183
+
// =============================================================================
184
+
// Demo
185
+
// =============================================================================
186
+
187
+
const main = async () => {
188
+
console.log("=== The Forest Election: The Announcement ===\n")
189
+
console.log("Sending announcement to all regions...")
190
+
console.log("(Each bird has 3 attempts with varying reliability)\n")
191
+
192
+
const startTime = Date.now()
193
+
194
+
// THIS is where the effects actually execute
195
+
const results = await runPromise(announceToAllRegions())
196
+
197
+
const elapsed = Date.now() - startTime
198
+
199
+
// Separate successes and failures
200
+
const delivered = results.filter(
201
+
(r): r is { _tag: "Delivered"; result: DeliveryResult } =>
202
+
r._tag === "Delivered",
203
+
)
204
+
const failed = results.filter(
205
+
(r): r is { _tag: "Failed"; region: Region; error: MessageError } =>
206
+
r._tag === "Failed",
207
+
)
208
+
209
+
// Report results
210
+
console.log("Results:")
211
+
console.log("─".repeat(50))
212
+
213
+
console.log(`\nDelivered: ${delivered.length}/4`)
214
+
delivered.forEach((d) => {
215
+
const flightTime = d.result.confirmationTime - startTime
216
+
console.log(` ✓ ${d.result.region}`)
217
+
console.log(` via ${d.result.deliveredBy} (${flightTime}ms)`)
218
+
})
219
+
220
+
if (failed.length > 0) {
221
+
console.log(`\nFailed: ${failed.length}/4`)
222
+
failed.forEach((f) => {
223
+
console.log(` ✗ ${f.region}`)
224
+
console.log(` ${formatError(f.error)}`)
225
+
})
226
+
}
227
+
228
+
console.log(`\nTotal time: ${elapsed}ms`)
229
+
console.log(
230
+
"(Note: parallel execution means total time ≈ longest single delivery)\n",
231
+
)
232
+
233
+
// Summary
234
+
if (delivered.length === 4) {
235
+
console.log("All regions notified successfully!")
236
+
} else if (delivered.length >= 2) {
237
+
console.log("Most regions notified. Failed regions will need follow-up.")
238
+
} else {
239
+
console.log(
240
+
"Delivery issues detected. Consider sending ground messengers.",
241
+
)
242
+
}
243
+
244
+
console.log("\n=== The forest knows its new president ===")
245
+
}
246
+
247
+
// Run multiple times to see different outcomes
248
+
const runDemo = async () => {
249
+
console.log("Running announcement (attempt 1 of 3)...\n")
250
+
await main()
251
+
252
+
console.log("\n" + "=".repeat(60) + "\n")
253
+
254
+
console.log("Running announcement (attempt 2 of 3)...\n")
255
+
await main()
256
+
257
+
console.log("\n" + "=".repeat(60) + "\n")
258
+
259
+
console.log("Running announcement (attempt 3 of 3)...\n")
260
+
await main()
261
+
}
262
+
263
+
runDemo()