How do you stop sending one email per comment?
The first comment opens a window, and the rest fall into it. The run parks with nothing running until somebody comments. That first event starts a five minute window, every comment inside it lands in the same run, and when the window closes one email goes out with all of them. Then the run parks again for the next burst.
Three groups, one under the other, and a single vertical line running down outside them on the left that marks the flow of data. Nothing travels along that line. Instead the stretch between two ends fills, from whoever is calling toward whoever is called, holds while that one works, and then drains back the way it came. The fill is always the same grey, the ink of the Palumb mark: the line belongs to Palumb, and which end the fill starts from already says who placed the call. It carries a small stop at every height where something happens.
First group, yourapp.com/backend: your own application, and the calls it makes into Palumb: trigger for commentBurst on topic.doc-12, sendEvent for comment.added · 1, sendEvent for comment.added · 2 and sendEvent for comment.added · 3. Neither the bubble nor its mark exists until you make that call, and the mark is a small teal square that fills in once Palumb has it. While a call is in flight the bubble's border turns and the line below it fills down to Palumb.
Second group, palumb, the durable engine: the one that is not an address, because it is not something you run. It appears when the trigger arrives, and holds one bubble that says running workflow, except while it is waiting: then it names what it waits for, waiting comment.added and collecting comment.added, with the elapsed count in front where the wait has a limit. At the end it says run complete. Its border turns for as long as the run lives, through every wait. Just under it the journal grows, one small violet token per step that has closed, each carrying that step's number.
One of those waits is a collection, and it is what this drawing is about: step window gathers 2 events before its window closes. While a window is open the bubble names the event it is gathering and counts what it already holds, and the count goes up at each arrival. Every arrival lights the bubble teal for a moment and starts nothing of yours: the line down to your code stays grey and empty. The step returns the whole lot at once, when the clock says so and not when the last event lands.
From the second group the fill runs down to the exact row that is about to run, and stops on it. It is not the channel of the call: your workflow is one signed endpoint, and the body replays from the top with the completed steps rehydrated until it reaches the row it has not run yet. The line is the flow of control, and control really does end up on that row.
Third group, yourapp.com/workflows/commentBurst: your workflow file itself, 14 lines of TypeScript, with its line numbers. In the margin of every line that calls a step there is a numbered circle, the way an editor marks a breakpoint: 1 for step.waitForEvent, 2 for step.collect, 3 for step.send, 4 for step.trigger. At rest the margin holds only the line numbers; a step's number appears when that step starts running.
When the fill reaches a row, a band lights it, the way a debugger marks where it has stopped, and the ring in its margin turns. The moment the step is recorded the number leaves the margin, a tick takes its place, and the number reappears as a token in the row under Palumb: you wrote the step, we are the ones who remember it ran.
While the run waits the line down to your code is grey and empty and no row is lit, while the run stays alive in Palumb. That is the frame that matters: for as long as the wait lasts your server does nothing at all and ours does.
The file has no branch in it, so the one path the drawing follows is the only path there is. It is printed in full below.
At rest, which is also what anyone who has asked for less motion sees, every step the run reached is ticked, the journal holds its 4 tokens, the bubble says run complete, and the line is empty: the drawing is the finished picture of this path.
comment-burst.ts
workflow("commentBurst", async ({ payload, subscriber, step }) => {
const first = await step.waitForEvent("first", {
event: "comment.added",
})
const rest = await step.collect("window", {
event: "comment.added",
until: minutesFrom(first.receivedAt, 5),
})
await step.send("burst", "email", () => comments([first, ...rest]))
return step.trigger("next", "commentBurst", subscriber.id, payload)
})How it works
The workflow starts once for the document (trigger) and then waits (step 1) for somebody to comment, with no deadline at all. Until that happens nothing of yours is running and nothing of ours is either.
The first comment (sendEvent) wakes the run, and that is the instant the window is measured from. For the next five minutes the run gathers (step 2) whatever else arrives, two more comments here, and neither of them wakes it. When the five minutes are up, one email goes out with all three (step 3).
Then the run opens a fresh window for the document (step 4) and ends. The next burst gets its own run, and the reader gets one email per burst instead of one per comment.
Waiting driven by the user rather than gathered: nudging someone who signed up and never came back, where the first event to arrive ends the run instead of filling it.
Everyone who joins gets in, and it costs nothing. Your invite goes out when the beta opens.
Join the beta