Effect for TypeScript, grades 7 and 8

One kitchen. One cook. A lot of smoothies.

Effect is a library that helps programmers write TypeScript that waits, fails, and cleans up without surprises. That sounds grown-up. It isn't. Every idea in it can be explained with a food truck, and that's what we're going to do.

Start with Lesson 1

Meet the cast

Sam, the cook

The only cook in the truck. Sam stands for the JavaScript engine: exactly one pair of hands, always doing one thing at a time.

Maya, the customer

Orders smoothies, gets receipts, holds recipe cards, and sometimes walks off before her order is ready. Maya stands for the code that asks for things.

Ty, the kitchen manager

Reads every recipe card before it reaches Sam. If a card forgot something, Ty stops it at the door. Ty stands for the TypeScript type checker.

The menu

Seven lessons. Each one adds a single new thing to the kitchen picture, so you never hold more than one new idea at a time.

Why a kitchen?

Because every hard word in this topic is really a kitchen word wearing a costume. "Asynchronous" is a toaster with a bell. A "Promise" is a receipt. An "Effect" is a recipe card. A "service" is a blender. A "fiber" is a bookmark. Once you can see the kitchen, the words stop being scary.

The code on these pages uses Effect 4.0 (release candidate). Every snippet was type-checked and run against effect@4.0.0-rc.118. There is very little code on purpose. The point this month is the ideas.

Lesson 1

Waiting Is Normal

JavaScript is a kitchen with exactly one cook. Lots of things in a program involve waiting: for a file, for the internet, for a timer. If the cook stands there staring at the oven, nothing else gets done. So JavaScript has a trick for waiting without freezing.

The story

Picture a food truck with one cook, Sam. An order comes in: toast and a smoothie.

The wrong way. Sam puts bread in the toaster and stands in front of it, arms crossed, for two minutes. The truck looks frozen.

The right way. The toaster gets a bell. Sam says "ring when you're done," walks away, and starts the smoothie.

Ding! Sam comes back for the toast. Sam never did two things at the same instant. Sam just never stood still.

That bell is the whole secret. The cook says: "Toaster, when you're done, ring the bell and I'll come back." In code, the "come back and do this" part is called a callback.

The picture

Async doesn't make the toaster faster. It stops Sam from standing still while the toaster works. The dashed bar is time Sam is not spending on toast.

How does Sam know the bell rang? Sam has a ticket rail. Every time a bell rings, a ticket goes on the rail: "toast is ready, go butter it." Whenever Sam's hands are free, Sam takes the next ticket. Programmers call this ticket rail the event loop. You don't need to remember that name today. You need to remember: one cook, a rail of tickets, hands never idle.

The event loop. Bells add tickets to the rail. Sam works through them one at a time, so nothing ever happens "at the same time," and nothing waits idle either.

The tiniest code

console.log("1. put bread in")

setTimeout(() => {
  console.log("3. 🔔 toast ready")   // this runs LATER, when the bell rings
}, 2000)

console.log("2. make smoothie")     // this runs RIGHT AWAY, Sam didn't wait

Run it and the numbers come out in order: 1, 2, then 3 two seconds later. The function inside setTimeout is the ticket Sam left for later. That's a callback.

The freeze test

The ball bounces and the counter ticks as long as Sam's hands are free. Make toast both ways and watch what happens to them. The blocking button really freezes this page for two seconds. That's the point.

ticks: 0

the rest of the kitchen

Check yourself

1. Sam is one person. Did Sam ever do two things at the exact same moment?

No. Sam did one thing, then another, then another. The toaster did its own work, but the toaster isn't Sam. One cook, one thing at a time, always.

2. Why does line "2" print before line "3", even though "3" is written above it?

Line 3 is inside the ticket Sam left for later. Sam keeps going down the list (prints 2), and only comes back for the ticket when the bell rings two seconds later.

3. A web page freezes when you click a button. In kitchen words, what did the programmer do wrong?

They made Sam stand and stare at something instead of leaving a ticket. While Sam stares, no other ticket gets done, so the page can't even redraw itself.

4. If Sam gets three bells at once, what happens?

Three tickets go on the rail. Sam does them one at a time, in the order they arrived.

Teacher notes

The word for "the cook stops and stares" is synchronous or blocking. The word for "leave a ticket, come back later" is asynchronous. Introduce those words only after the story is solid.
Resist saying "multithreading." JavaScript in the browser and in Node has one cook. Fibers (Lesson 6) will feel like cheating later, and it's worth having the one-cook rule firmly set first.
Callbacks get messy when you need "when this is done, do that, and when that is done, do this." Show a three-deep nested setTimeout on the board and ask if anyone wants to read it. That mess is why Lesson 2 exists.
The freeze demo uses a real busy-wait loop. Kids will ask why the ball stops but the toaster still "finishes." Answer: the ball is drawn by Sam. The toaster timer is not Sam.

Lesson 2

Promises: The Receipt

A Promise is a receipt for a value that isn't ready yet. You order a smoothie, you get a receipt, and the receipt says "your smoothie will be here soon, or we'll tell you why not."

The story

She orders. Sam doesn't hand her a smoothie. Sam hands her a receipt with a number on it.

The receipt is not the smoothie. It's a promise of one. And notice: the blender started the moment she ordered.

Two endings. Her number is called and here's the smoothie. Or: "Sorry, we're out of mango." Either way, the receipt is finished.

Three things can be true about that receipt at any moment:

Pending: still blending. You're holding the receipt, waiting.
Fulfilled: your number is called, here's your smoothie. The receipt "turned into" the value.
Rejected: "Sorry, we're out of mango." The receipt turned into a reason it failed.

Once a receipt is fulfilled or rejected, it never changes again. A smoothie doesn't un-blend.

A receipt moves from pending to exactly one of two final states, and then stays there. There is no arrow back.

What you can do with a receipt

You can write instructions on the back of it:

.then(...) means "when it's ready, do this with it."
.catch(...) means "if it fails, do this instead."

orderSmoothie("mango")
  .then((smoothie) => console.log("Yum:", smoothie))
  .catch((reason) => console.log("Oh no:", reason))

The order machine

Pick a flavor and order. Watch the receipt change state, and watch which instruction on the back of it runs. Kiwi is out of stock today.

🥭 mango 🥝 kiwi

async and await: writing it like a normal story

Writing everything in .then chains gets awkward. So JavaScript lets you write it top to bottom:

async function lunch() {
  const smoothie = await orderSmoothie("mango")   // wait here, but Sam stays busy elsewhere
  console.log("Yum:", smoothie)
}

async on a function means: "this function hands back a receipt, not the answer."
await means: "pause this story until the receipt is fulfilled, then continue." The cook is not frozen while we wait. Other tickets still get done. It's only this story that pauses.

If the receipt is rejected, await throws, and you catch it with a normal try/catch:

async function lunch() {
  try {
    const smoothie = await orderSmoothie("mango")
    console.log("Yum:", smoothie)
  } catch (reason) {
    console.log("Oh no:", reason)
  }
}

Three things a receipt can't tell you

Hold up a real receipt and ask what's missing. In code, a Promise<Smoothie> tells you the happy answer and nothing about failures, reuse, or cancelling. Lesson 3 fixes all three.

Check yourself

1. Is the receipt the smoothie? What is it, then?

No. It's a promise of a smoothie: a placeholder that will turn into either the smoothie or a reason you didn't get one.

2. When does the blender start: when you order, or when you read the receipt?

When you order. Creating the Promise starts the work. Reading the receipt (calling .then) doesn't start or stop anything.

3. What are the three states? Can a receipt go from Fulfilled back to Pending?

Pending, fulfilled, rejected. No. Once settled, a Promise never changes again.

4. Your friend says "await freezes the whole program." Use the kitchen to explain why they're wrong.

await pauses one story (one function) until its receipt is ready. Sam keeps taking other tickets off the rail meanwhile. The truck never freezes; only that one customer's story is waiting.

Teacher notes

A Promise is a real thing you can print. console.log(orderSmoothie("mango")) shows Promise { <pending> }. Kids love seeing the word "pending" for real.
Reinforce that async/await is only a nicer way to write .then. Nothing new happens underneath.
The "three things a receipt can't tell you" figure is the bridge to Effect. If you have to cut something from this lesson, don't cut that.
A fake orderSmoothie for the demo: new Promise((resolve, reject) => setTimeout(() => flavor === "mango" ? resolve("mango smoothie") : reject("out of " + flavor), 1000)).

Lesson 3

Effects: The Recipe Card

An Effect is a recipe card, not a meal. It describes what to do. Nothing happens until you hand the card to the kitchen and say "run it." And the card has three lines on it that a receipt never had.

The story

Remember the receipt? The blender started the moment you ordered. You couldn't reorder from it, couldn't cancel it, and it didn't say what could go wrong. Now imagine the counter hands you a recipe card instead.

A card is just paper. Holding it makes no smoothie. The blender is off.

You can copy it. Read it, photocopy it, staple it to another card, hand it around. Still no smoothie.

Only handing it to the kitchen makes a smoothie. Programmers say you run the effect.

That one difference fixes all three receipt problems:

Receipt (Promise)

Starts the moment it's made
One use
Doesn't say what can go wrong
Doesn't say what it needs

Recipe card (Effect)

Starts only when you run it
Run it as many times as you like
Has a "Can go wrong" line
Has a "Needs" line

The three lines on the card

The three lines on the card are the three slots of the type. Say it as a sentence every time until it's automatic.

Effect<Smoothie, OutOfMango, Blender>
// slot 1: you get · slot 2: can go wrong · slot 3: needs

The tiniest code

import { Effect, Console } from "effect"

// Making a card. NOTHING RUNS YET.
const sayHi = Console.log("hi!")           // Effect<void>

// Still nothing runs. We're just stapling two cards together into one.
const sayHiTwice = Effect.andThen(sayHi, sayHi)

// NOW it runs.
Effect.runPromise(sayHiTwice)              // prints "hi!" twice

Compare with a Promise: console.log("hi!") prints immediately. There is no "card" step.

Receipt vs. card

On the left, a receipt for one smoothie. On the right, a recipe card. Press each button a few times and count the smoothies.

Receipt (Promise)

One receipt was created when the page loaded. The blender already ran.

Recipe card (Effect)

The card is a plan. Nothing has run.

Writing a recipe with steps: Effect.gen

Real recipes have several steps. Effect.gen lets you write them top to bottom, like the async/await story from Lesson 2. The magic word is yield*, which you read as "do this step and hand me the result."

import { Effect, Console } from "effect"

const getMango = Effect.succeed("🥭")          // a card that always gives a mango
const getIce   = Effect.succeed("🧊")          // a card that always gives ice

const smoothie = Effect.gen(function* () {
  const mango = yield* getMango                 // do this step, hand me the mango
  const ice   = yield* getIce                   // do this step, hand me the ice
  yield* Console.log(`blending ${mango} + ${ice}`)
  return "🥤"                                   // the "You get" line
})
// smoothie : Effect<string>   (gives a string, nothing can go wrong, needs nothing)

Effect.runPromise(smoothie).then(console.log)   // blending 🥭 + 🧊  then  🥤

The function* with a star is a generator. You don't need to know what that means this month. Treat Effect.gen(function* () { ... }) as "here begins a recipe" and yield* as "do this step." And notice: smoothie is still just a card. You could run it a hundred times and get a hundred smoothies.

Check yourself

1. You have const s = makeSmoothie() where makeSmoothie returns an Effect. Has a smoothie been made?

No. You're holding a card. A smoothie is made only when something runs the card.

2. Read this out loud as a sentence: Effect<Toast, BreadIsMoldy, Toaster>.

"An Effect that gives you Toast, might fail with BreadIsMoldy, and needs a Toaster."

3. What does never mean in the middle slot? In the last slot?

Middle: nothing can go wrong. Last: it needs nothing, so it's ready to run.

4. Why can you run the same Effect twice, but not "re-await" the same Promise to get a second smoothie?

The Effect is a plan; running it twice does the plan twice. The Promise is the result of work that already happened; awaiting it again just hands you the same finished result.

Teacher notes

The phrase to repeat: "plan, not action." Have students say "plan" when they see Effect. and "action" when they see Effect.runPromise.
Why want a card instead of the meal? Because cards can be checked before cooking. Ty can look at the card and say "you forgot to handle OutOfMango" before anyone turns on a blender. Lesson 4 shows it.
Effect.succeed(x) is a card that just hands you x. Effect.fail(e) is a card that just fails with e. Those two plus Effect.gen are enough for this unit.
Effect.runPromise gives back a Promise, so the card world plugs into the receipt world at the very edge of the program. Real programs call it once, at the door. Everything inside is cards.

Lesson 4

Errors You Can See

The card says what can go wrong, so the compiler makes you deal with it. Effect also separates "problems we expected" from "the kitchen caught fire," and gives you tools like retry and timeout that snap onto any card.

The story

Two very different things can go wrong at the smoothie counter.

Out of mango. Annoying, but normal. It's going to happen sometimes. A good card lists it, and a good cook has a plan: offer strawberry.

Kitchen fire. Nobody writes "fire" on a smoothie card. It's not a smoothie problem, it's a bug in the building. You don't handle it with a strawberry.

Ty checks the card. If the error line still lists something nobody planned for, Ty stops it at the door. Add the plan, and the card is cleared.

Effect calls the first kind an error (expected, written on the card) and the second kind a defect (unexpected, a bug). The compiler makes you deal with errors. Defects crash loudly, which is what you want, because hiding a fire is worse than seeing it.

Name tags for errors

Each expected error gets a name tag so you can tell them apart:

import { Data } from "effect"

class OutOfMango extends Data.TaggedError("OutOfMango") {}
class BlenderJammed extends Data.TaggedError("BlenderJammed")<{ readonly speed: number }> {}

That's a whole error type. The string in quotes is the name tag. Now a card can list them:

import { Effect } from "effect"

const getMango = Effect.gen(function* () {
  if (Math.random() < 0.3) {
    return yield* Effect.fail(new OutOfMango())     // the "can go wrong" line
  }
  return "🥭"
})
// getMango : Effect<string, OutOfMango>
//                           ^ TypeScript figured this out on its own

Nobody wrote OutOfMango in the type. Ty read the recipe and filled in the "Can go wrong" line alone.

The picture: a card going through the kitchen

Three ways out of "run it." Only the middle one is the cook's business. The error line on the card is the list of things the cook is expected to have a plan for.

Catching one specific error

const getFruit = getMango.pipe(
  Effect.catchTag("OutOfMango", () => Effect.succeed("🍓"))
)
// getFruit : Effect<string>      <-- OutOfMango is GONE from the error line

Look at what happened to the type. Before: Effect<string, OutOfMango>. After: Effect<string>. Ty saw that we wrote a plan for OutOfMango and crossed it off the card. If a card still has errors on it when you reach Effect.runPromise, that's your reminder that you haven't planned for them.

Effect.catch (no tag) is the "catch anything on the error line" version. It still doesn't catch defects. Fires are not on the error line.

Two tools that snap onto any card

Because a card is just a plan, you can wrap a plan around a plan.

// Retry: "if it fails, try again, up to 3 more times."
const stubbornMango = Effect.retry(getMango, { times: 3 })

// Timeout: "give up if it takes longer than 2 seconds."  The error line grows:
const quickMango = Effect.timeout(getMango, "2 seconds")
// quickMango : Effect<string, OutOfMango | TimeoutError>

Try doing that to a Promise. You can't wrap a plan around a receipt, because the receipt already started.

Build the card, watch the error line

Snap tools onto getMango and watch the type change. Ty only lets a card through when its error line is empty.

retry({ times: 3 }) timeout("2 seconds") catchTag("OutOfMango", 🍓)

Check yourself

1. "Out of mango" versus "kitchen fire": which one belongs on the recipe card, and why?

Out of mango. It's expected and specific to this recipe, so the cook should have a plan. A fire is a bug in the building, not part of any recipe.

2. Before catchTag, the type was Effect<string, OutOfMango>. After, it was Effect<string>. Who crossed the error off, and how did they know they could?

The type checker (Ty). It saw a handler for the exact name tag "OutOfMango," so that failure can no longer escape the card.

3. Why can you wrap retry around an Effect but not around a Promise?

An Effect is a plan that hasn't started, so "do this plan again if it fails" makes sense. A Promise has already started; there's nothing to re-run.

4. Effect.timeout adds an error to the card. Is that a bad thing?

No. It's honest. The card can now fail a new way, and the card says so.

Teacher notes

The single most important moment in this unit is showing the error type disappear when you add catchTag. Do it live with hover-over types in the editor. Let them see the red squiggle when they forget.
Data.TaggedError("Name") makes a class with a _tag field. The _tag is literally the name tag. console.log(err._tag) proves it.
Defects come from throw inside plain code, or Effect.die. You can catch them with Effect.catchDefect, but that's for the fire-alarm layer of a program, not recipes.
Ask students to write the "Can go wrong" line for logging into a game: WrongPassword, ServerDown, TooManyAttempts. That makes it click that errors are a list of known things, not "stuff happened."

Lesson 5

Asking for Help: Services and Layers

A recipe says what it needs. The kitchen supplies it. The smoothie recipe says "Needs: a blender." It does not say which blender, and it definitely doesn't build one. That's the third line on the card, and it's what makes recipes testable and swappable.

The story

The smoothie recipe says "blend for 30 seconds." It doesn't say "go buy a Blendtec 575." Any blender will do. On the day, the kitchen hands the cook whichever blender it has.

The recipe asks. Sam holds out a hand: "blender, please." The recipe never says which blender.

The kitchen provides. For a practice kitchen, a pretend blender that instantly hands back a smoothie. Same recipe, no mess. Programmers call this a test.

Ty checks the Needs line too. Try to run a card that still needs something, and Ty stops it before Sam even sees it.

In Effect, a thing a recipe needs is called a service. The way the kitchen supplies it is called a layer.

The picture

One recipe, two kitchens. Providing a layer shrinks the Needs line to never, meaning "nothing." Only then can the card run.

The tiniest code

Step 1. Describe the service. Just the shape, what a blender can do. No real blender yet.

import { Context, Effect } from "effect"

class Blender extends Context.Service<Blender, {
  readonly blend: (stuff: string) => Effect.Effect<string>
}>()("Blender") {}

Read it as: "There is a service called Blender. Any Blender must have a blend step."

Step 2. Write a recipe that asks for a Blender.

const smoothie = Effect.gen(function* () {
  const blender = yield* Blender                 // "hand me whatever Blender the kitchen has"
  return yield* blender.blend("🥭 + 🧊")
})
// smoothie : Effect<string, never, Blender>
//                                  ^ the "Needs" line, filled in by TypeScript

Step 3. Build a real one and a pretend one. These are layers.

import { Layer, Console } from "effect"

const RealBlender = Layer.succeed(Blender, {
  blend: (stuff) => Console.log("WHIRRRR " + stuff).pipe(Effect.as("🥤"))
})

const FakeBlender = Layer.succeed(Blender, {
  blend: (_stuff) => Effect.succeed("🥤 (pretend)")
})

Step 4. Provide one and run.

Effect.runPromise(smoothie.pipe(Effect.provide(RealBlender)))   // WHIRRRR 🥭 + 🧊  →  🥤
Effect.runPromise(smoothie.pipe(Effect.provide(FakeBlender)))   // 🥤 (pretend)

Pick a kitchen

Same smoothie card every time. Choose what the kitchen provides, then run it.

RealBlender FakeBlender nothing

Layers stack

A real kitchen needs a blender and a fridge and a sink. Layers combine:

const Kitchen = Layer.mergeAll(RealBlender, RealFridge)
Effect.runPromise(bigRecipe.pipe(Effect.provide(Kitchen)))

A layer can itself need things. Layers are recipes for building appliances. We don't go deeper than this picture this month.

Check yourself

1. The smoothie recipe says "Needs: Blender." Does it say which blender? Why is that good?

No. So the same recipe works with any blender: a real one today, a pretend one for practice, a new one when the old one breaks. The recipe never changes.

2. What's the point of a pretend blender?

Testing the recipe without the mess. You can check every step of the card in seconds, with no fruit and no cleanup.

3. After Effect.provide(RealBlender), what does the "Needs" line say? What word is that?

never, which means "nothing." The card is ready to run.

4. You try to run the card without providing a blender. Who stops you, and when?

Ty, the type checker, at compile time. Before the blender would have spun, before the program even starts.

Teacher notes

The grown-up term is dependency injection. Don't say it. "The recipe asks, the kitchen provides" is exactly the same idea.
Context.Service<Self, Shape>()("Name") has an odd double-parentheses shape. Tell students to copy it exactly; it's a TypeScript quirk, not an Effect idea.
Layer.succeed(Tag, impl) is "here's a ready-made appliance." Layer.effect(Tag, effect) is "here's a recipe for building the appliance," for when building it can fail or needs other things.
In-class exercise: half the room writes a Fridge service with take(item) that can fail with OutOf(item) (Lesson 4!). The other half writes its two layers.

Lesson 6

Many Things at Once: Fibers

One cook can keep many recipes going by using bookmarks, and can cleanly stop any of them. Effect calls a bookmark in a running recipe a fiber. Fibers let you run recipes side by side, race them, and interrupt them, which Promises can't do.

The story

Remember: still one cook, Sam. Sam is making three smoothies for three customers. Sam does not grow extra arms.

Bookmarks. Sam puts a bookmark in recipe 1 while it blends, starts recipe 2, bookmarks that, starts recipe 3. Three recipes in progress, one cook.

Each bookmark is a fiber. It remembers where in the recipe we were, so Sam can pick it back up when the bell rings.

Customer 2 leaves. With a receipt, too bad, the smoothie gets made anyway. With a fiber, Sam pulls the bookmark out. Effect calls this interruption.

The picture

Sam only works during the orange bits. The gray stretches overlap, which is why three 3-second smoothies take about five seconds, not nine. Recipe 2 never gets its pour step.

The tiniest code

Run several cards at once. Effect.all takes a list of cards and gives back one card that produces a list of results. The concurrency option is "how many bookmarks may Sam have open at once."

import { Effect } from "effect"

const makeSmoothie = (name: string) =>
  Effect.sleep("3 seconds").pipe(Effect.as(`${name} 🥤`))

const three = Effect.all(
  [makeSmoothie("mango"), makeSmoothie("berry"), makeSmoothie("kiwi")],
  { concurrency: "unbounded" }      // as many bookmarks as needed
)
// three : Effect<string[]>

Effect.runPromise(three).then(console.log)   // ~3 seconds, not 9

Race. Two cards start; the first to finish wins, and the loser is interrupted (its bookmark is pulled).

const fastest = Effect.race(makeSmoothie("mango"), makeSmoothie("berry"))

A bookmark you can hold. Effect.forkChild starts a card in the background and hands you the fiber. Fiber.join waits for it. Fiber.interrupt stops it.

import { Effect, Fiber, Console } from "effect"

const program = Effect.gen(function* () {
  const fiber = yield* Effect.forkChild(makeSmoothie("mango"))   // start it, keep the bookmark
  yield* Console.log("customer is waiting...")
  yield* Effect.sleep("1 second")
  yield* Console.log("customer left!")
  yield* Fiber.interrupt(fiber)                                  // pull the bookmark
  yield* Console.log("stopped the mango smoothie")
})

Effect.runPromise(program)

Try that with a Promise. There is no way to stop orderSmoothie("mango") once it's called.

Three smoothies, one cook

Each smoothie takes 3 seconds of blending. Pick how many bookmarks Sam may hold, start, and time it. While it runs, customer 2 can leave.

concurrency: 1 2 "unbounded" elapsed: 0.0 s

Race keeps the first result and pulls the other bookmark. The interrupted fiber still runs its cleanup (Lesson 7).

Check yourself

1. Did Sam ever do two things at the exact same instant? Then how did three smoothies take three seconds?

No. Sam only did the short steps. The blenders did the long waiting parts, all overlapping, while Sam held three bookmarks.

2. What is a fiber, in kitchen words?

A bookmark in a half-finished recipe: it remembers where Sam was, so Sam can come back to it, or pull it out.

3. A customer leaves. What happens to their smoothie with a Promise? With a fiber?

Promise: it gets made anyway; nothing can stop it. Fiber: Sam interrupts it, the recipe stops at its next step, and any cleanup it promised still runs.

4. In Effect.all with concurrency: 2, how long do three 3-second smoothies take?

About 6 seconds. Two run together (3 s), then the third runs alone (3 s). Try it in the demo above.

Teacher notes

The word for "many things in progress at once" is concurrency. It's not "many things happening at the same instant," which is parallelism and needs more cooks. Say "in progress," never "at the same time," and you'll avoid a year of confusion.
Effect.forkChild makes the fiber a child of the current one. If the parent finishes or is interrupted, the child is interrupted too. Effect 4 also has forkScoped and forkDetach for other lifetimes; skip them.
Leaving out concurrency means one at a time.
Interruption is polite. A fiber isn't killed mid-instruction; it stops at the next step boundary and runs its cleanup. Compare pulling the plug to pressing the off button.

Lesson 7

Cleaning Up

Whatever you borrow, you give back, even when things go wrong. Effect has a built-in rule for "get a thing, use it, always put it back," and it holds no matter how the recipe ends: success, error, or interruption.

The story

Maya checks a book out of the library. Three ways her afternoon can go.

She reads it and returns it. The happy ending.

She spills juice on chapter three. An error. She still has to return it.

She's called home mid-chapter. An interruption. She still returns the book on the way out.

The return is not optional. It doesn't care why she stopped reading. Kitchen version: Sam turns on the blender. Whether the smoothie succeeds, the fruit was rotten, or the customer left and the recipe was interrupted, the blender gets turned off. A blender left running overnight is how kitchens burn down. Effect calls this pattern acquire and release, and the guarantee is: release always runs.

The picture

Every arrow out of "use" goes through "release." There is no path that skips it.

The tiniest code

import { Effect, Console } from "effect"

const blenderOn  = Console.log("blender ON  🔛")
const blenderOff = Console.log("blender OFF ⏹️")

const useBlender = Effect.acquireRelease(
  blenderOn,            // acquire
  () => blenderOff      // release: ALWAYS runs
)

const smoothie = Effect.gen(function* () {
  yield* useBlender
  yield* Console.log("blending...")
  yield* Effect.fail(new Error("rotten fruit!"))   // uh oh
  yield* Console.log("pouring")                    // never reached
})

Effect.runPromise(Effect.scoped(smoothie)).catch(() => {})
// blender ON  🔛
// blending...
// blender OFF ⏹️        <-- ran anyway

Delete the Effect.fail line and you'll see ON, blending, pouring, OFF. Put it back: ON, blending, OFF. Either way, OFF.

Three endings, one release

Choose how the recipe ends, then run it. Watch the last line of the log and the blender.

success rotten fruit (error) customer left (interrupt)

What's Effect.scoped?

The library book has a due date: how long you're allowed to keep it. Effect calls that window a scope. Effect.acquireRelease adds "Needs: a Scope" to the card's third line, because the card needs to know when to return things. Effect.scoped says "the scope is this recipe: return everything when it ends." Layers (Lesson 5) also make scopes, so a blender acquired in a layer is returned when the app shuts down.

You don't need to understand scopes deeply this month. You need: acquireRelease borrows, scoped sets the due date, release always happens.

Why this is a big deal

With a Promise, there's no "interrupted" path at all, so people forget cleanup on the "customer left" case, because that case doesn't exist for them. Then a real program runs for a week and has ten thousand blenders still on. Effect makes the interrupted path a first-class thing, and cleanup runs on it too.

Check yourself

1. Name the three ways a recipe can end. Which of them skips the release step?

Success, error, interruption. None of them skip release.

2. Why is "turn the blender off" not just the last line of the recipe?

Because if a line before it fails or gets interrupted, the last line is never reached. Release has to be attached to the borrowing, not written at the end.

3. In library words, what's a scope?

The due date: the window of time you're allowed to hold what you borrowed.

4. A friend says "I'll just put cleanup in the .catch of my Promise." What case did they forget?

The interrupted case. Promises don't have one, so their cleanup never runs when a customer walks away.

Teacher notes

acquireRelease(acquire, release) returns the acquired thing, so you can do const blender = yield* useBlender and then use it. The example throws it away for simplicity.
Effect.ensuring(cleanup) is the simpler cousin: "after this card, always run cleanup." Effect.addFinalizer registers cleanup from inside a gen block.
A closer for the unit: draw the full smoothie card on the board with all three lines filled in, a retry and timeout wrapped around it, a Blender layer provided, and acquireRelease keeping the blender safe. Then ask: "What can go wrong that we haven't written down?" The answer, "a defect, and we'd see it loudly," is the whole philosophy in one sentence.

Reference

Promise vs. Effect, on one page

Everything from the seven lessons, side by side. The receipt on the left, the recipe card on the right.

Question	Promise (the receipt)	Effect (the recipe card)
What is it?	A value that isn't ready yet	A plan for getting a value
When does it start?	The moment you make it	Only when you run it
Can you run it twice?	No. One receipt, one smoothie	Yes, as many times as you like
Does the type say what can go wrong?	No: `Promise<Smoothie>`	Yes: `Effect<Smoothie, OutOfMango>`
Does the type say what it needs?	No	Yes: `Effect<Smoothie, OutOfMango, Blender>`
Can you cancel it?	No	Yes. Interrupt the fiber; cleanup still runs
Write steps top to bottom	`async` / `await`	`Effect.gen` / `yield*`
"Do this when it succeeds"	`.then(f)`	`Effect.map` / `Effect.andThen`
"Do this if it fails"	`.catch(f)`, catches everything, mystery box	`Effect.catchTag("Name", f)` for one error, `Effect.catch` for all listed errors
Try again on failure	Write a loop yourself	`Effect.retry(card, { times: 3 })`
Give up after a while	Hard: a second Promise and a timer	`Effect.timeout(card, "2 seconds")`
Several at once	`Promise.all([...])`	`Effect.all([...], { concurrency: n })`
First one wins	`Promise.race([...])`, loser keeps running	`Effect.race(a, b)`, loser is interrupted
Always clean up	`try { } finally { }`, no interrupt case	`Effect.acquireRelease`: success, error, and interrupt
Ask for a helper	Import it or pass it in by hand	`yield* Blender`, then `Effect.provide(layer)`
Turn it into the other	(a Promise is already running)	`Effect.runPromise(card)` at the door of the program

Reading an Effect type out loud

Effect<Smoothie, OutOfMango, Blender>

"An Effect that gives you a Smoothie, might fail with OutOfMango, and needs a Blender."

never in slot 2: nothing can go wrong.
never in slot 3: needs nothing. Ready to run.
Trailing nevers can be left off: Effect<number> means Effect<number, never, never>.

The five lines of Effect 4 you actually need this month

import { Effect, Console, Context, Layer, Data, Fiber } from "effect"

Effect.gen(function* () { const x = yield* step; return x })   // a recipe with steps
class OutOfMango extends Data.TaggedError("OutOfMango") {}     // a named error
class Blender extends Context.Service<Blender, { ... }>()("Blender") {}   // a needed thing
Layer.succeed(Blender, { ... })                                 // a way to provide it
Effect.runPromise(card.pipe(Effect.provide(layer)))            // the door out of the kitchen

Kitchen word, programmer word

Kitchen picture	Programmer word	What it means
One cook	single-threaded	JavaScript does one instruction at a time. Always.
Standing and staring at the toaster	blocking / synchronous	Waiting in a way that freezes everything else.
Leaving a ticket and walking away	asynchronous	Waiting in a way that lets other work happen.
The ticket you leave	callback	A function to run later, when something finishes.
The ticket rail	event loop	The list the cook checks whenever hands are free.
A receipt for a smoothie	Promise	A value that isn't ready yet. Starts the moment it's made.
A recipe card	Effect	A plan for producing a value. Does nothing until run.
"You get" / "Can go wrong" / "Needs"	Success / Error / Requirements	The three slots of the Effect type.
Nothing on that line	`never`	Nothing can go wrong, or nothing is needed.
Out of mango	error	A known failure, written on the card, must be handled.
Kitchen fire	defect	A bug. Not on the card. Crashes loudly on purpose.
A name tag on a problem	tagged error	An error class with a `_tag` string.
An appliance the recipe asks for	service	A described capability, like "a Blender that can blend."
The kitchen supplying the appliance	layer	A way to build or provide a service.
Ty, the kitchen manager	the type checker	Reads every card before it can run. Stops incomplete ones.
A bookmark in a half-done recipe	fiber	A running Effect that can be paused, resumed, or stopped.
Pulling the bookmark out	interruption	Stopping a fiber cleanly; its cleanup still runs.
Borrow it, always return it	acquire / release	Get a resource and guarantee cleanup on every ending.
The due date	scope	The window during which a borrowed resource is held.