Ritchie's features look conventional on the surface, but they have slight twists that combine with each other to yield a smoother development process. That gets you to "done correctly" faster. The not so secret sauce is that Ritchie is designed for an abstract machine that is a distributed system rather than one computer.
Let's take a short trip with Ritchie against the reigning productivity champion, TypeScript, to see what that buys.
Let's Go Online Shopping!
Say you're building an online shopping checkout flow. You have three APIs as building blocks.
| API | Purpose | Latency |
|---|---|---|
Pricing.quote(sku) | returns the price, given an SKU | 300 ms |
Inventory.check(sku) | returns the stock, given an SKU | 200 ms |
Ledger.record(sku, price) | records a sale | 100 ms |
We'll keep things simple, for obvious reasons...
The Happy Path
The product manager says: check the item's price and, if it is in stock, record the sale. Out of stock items return an error.
Here's the little TypeScript for it.
export async function checkout(sku: string): Promise<string> {
const price = await pricing.quote(sku);
const stock = await inventory.check(sku);
if (stock === 0) throw new SoldOut(sku);
await ledger.record(sku, price);
return `sold at $${price}`;
}
Here's the Ritchie equivalent. Ritchie has network APIs as a first class feature. @Pricing is the pricing service, and quote is its endpoint. So wherever you see @, it's a remote call.
checkout(String sku) -> String {
Decimal price = @Pricing.quote(sku)
Int stock = @Inventory.check(sku)
if stock == 0 { return SoldOut! { sku: sku } }
@Ledger.record(sku, price)
return f"sold at ${price}"
}
Both snippets look line-for-line identical, apart from syntax. Note that we use the Decimal type for money, which behaves better than floating point.
The Unhappiness Guards
Good product design always pays attention to unhappy situations and failures as much as successes. We add the following safeguards:
- Pricing goes down. When Pricing has an outage, we charge the list price. Anything else Pricing complains about is the caller's problem.
- Products get discontinued. Pricing or Inventory can report that a product is gone, and the customer should hear about it either way.
- The Ledger fails. The connection to the Ledger can drop after the write has gone out. The sale may have happened, and a blind retry could charge the customer twice, so the response is "reconcile" and something has to reconcile it later.
export async function checkout(sku: string): Promise<string> {
+ try {
- const price = await pricing.quote(sku);
+ const price = await pricing.quote(sku).catch((e) => {
+ if (!(e instanceof HttpError && e.status === 503)) throw e;
+ return listPrice(sku);
+ });
const stock = await inventory.check(sku);
if (stock === 0) throw new SoldOut(sku);
+ try {
await ledger.record(sku, price);
+ } catch (e) {
+ if (e instanceof HttpError) throw e;
+ throw new Reconcile(sku);
+ }
return `sold at $${price}`;
+ } catch (e) {
+ if (e instanceof HttpError && e.status === 410) throw new Discontinued(sku);
+ throw e;
+ }
}
TypeScript needs nested try blocks because once an error is raised, there is no reaching back into the code that raised it. There are now twice as many lines for error checking as for successful functionality. So much for a simple checkout!
checkout(String sku) -> String {
+ {
- Decimal price = @Pricing.quote(sku)
+ Decimal price = @Pricing.quote(sku) handle Unavailable! => listPrice(sku)
Int stock = @Inventory.check(sku)
if stock == 0 { return SoldOut! { sku: sku } }
@Ledger.record(sku, price)
return f"sold at ${price}"
+ } handle {
+ Unverified! => return Reconcile! { sku: sku }
+ }
}
Ritchie only goes from 7 to 11 lines. Crucially, the happy path is still clearly consolidated, so it's a lot easier to follow the business logic while reading Ritchie compared to TypeScript.
Ritchie handles the pricing fallback inline. An unhandled error bubbles up to the caller, so "anything else", Discontinued! included, needs no code. The runtime reports the lost ledger write as its own error, Unverified!.
This is one step ahead of TypeScript already, because the Ritchie runtime tracks how far a write got, even inside the Ledger. If the call failed before the Ledger reached the point where it actually writes, the error is Unmodified! instead of Unverified!. So the Ritchie program starts a (definitely slow, potentially manual) reconciliation only when it really can't be sure.
The SREs Have a Say
Things were going swimmingly for a month, until last week a stuck dependency took checkout down. The SREs now have a rule: every call runs under a time budget, and a checkout that runs out of it responds instead of hanging.
+ const BUDGET_MS = Number(process.env.CHECKOUT_BUDGET_MS);
+
export async function checkout(sku: string): Promise<string> {
+ const signal = AbortSignal.timeout(BUDGET_MS);
try {
- const price = await pricing.quote(sku).catch((e) => {
+ const price = await pricing.quote(sku, { signal }).catch((e) => {
if (!(e instanceof HttpError && e.status === 503)) throw e;
return listPrice(sku);
});
- const stock = await inventory.check(sku);
+ const stock = await inventory.check(sku, { signal });
if (stock === 0) throw new SoldOut(sku);
try {
- await ledger.record(sku, price);
+ await ledger.record(sku, price, { signal });
} catch (e) {
if (e instanceof HttpError) throw e;
throw new Reconcile(sku);
}
return `sold at $${price}`;
} catch (e) {
if (e instanceof HttpError && e.status === 410) throw new Discontinued(sku);
+ if (e === signal.reason) throw new OutOfTime();
throw e;
}
}
Ritchie's change is a grand total of one line vs. 6 for TypeScript.
checkout(String sku) -> String {
{
Decimal price = @Pricing.quote(sku) handle Unavailable! => listPrice(sku)
Int stock = @Inventory.check(sku)
if stock == 0 { return SoldOut! { sku: sku } }
@Ledger.record(sku, price)
return f"sold at ${price}"
} handle {
Unverified! => return Reconcile! { sku: sku }
+ Cancelled! => return OutOfTime!
}
}
Deadlines are built into the runtime, so there is nothing to thread through your code. Every entry already runs its calls under a budget, 1400 ms unless configured, and holds back an extra buffer to deliver the response. Every remote call inherits what is left of it. Honestly, this would've been a zero-code change if we hadn't decided to rename the error from Cancelled! to OutOfTime!.
TypeScript has to thread the deadline by hand, and every call must remember to carry it. Leave { signal } off one of them and that call ignores the budget, and the compiler has no opinion on the matter.
Customers Want to Buy Multiple Items
Product has noticed that people would be happier to buy multiple things in one checkout. So checkout now takes a whole cart. An SKU that is sold out or discontinued gets skipped and counted, and the rest of the cart carries on. So we do what anyone would do — we add a loop.1
const BUDGET_MS = Number(process.env.CHECKOUT_BUDGET_MS);
- export async function checkout(sku: string): Promise<string> {
+ export async function checkout(skus: string[]): Promise<string> {
const signal = AbortSignal.timeout(BUDGET_MS);
+ let total = 0, skipped = 0, reconcile = 0;
+ for (const sku of skus) {
try {
const price = await pricing.quote(sku, { signal }).catch((e) => {
if (!(e instanceof HttpError && e.status === 503)) throw e;
return listPrice(sku);
});
const stock = await inventory.check(sku, { signal });
- if (stock === 0) throw new SoldOut(sku);
+ if (stock === 0) { skipped += 1; continue; }
try {
await ledger.record(sku, price, { signal });
} catch (e) {
if (e instanceof HttpError) throw e;
- throw new Reconcile(sku);
+ reconcile += 1; continue;
}
- return `sold at $${price}`;
+ total += price;
} catch (e) {
- if (e instanceof HttpError && e.status === 410) throw new Discontinued(sku);
- if (e === signal.reason) throw new OutOfTime();
+ if (e instanceof HttpError && e.status === 410) { skipped += 1; continue; }
+ if (e === signal.reason) throw new OutOfTime(total);
throw e;
}
+ }
+ return `total $${total}, skipped ${skipped}, reconcile ${reconcile}`;
}
- checkout(String sku) -> String {
+ checkout(String[] skus) -> String {
+ Decimal total = 0.00
+ Int skipped, reconcile = 0, 0
- {
+ for sku in skus {
Decimal price = @Pricing.quote(sku) handle Unavailable! => listPrice(sku)
Int stock = @Inventory.check(sku)
- if stock == 0 { return SoldOut! { sku: sku } }
+ if stock == 0 { skipped += 1; continue }
@Ledger.record(sku, price)
- return f"sold at ${price}"
+ total += price
} handle {
- Unverified! => return Reconcile! { sku: sku }
- Cancelled! => return OutOfTime!
+ Discontinued! => { skipped += 1; continue }
+ Unverified! => { reconcile += 1; continue }
+ Cancelled! => return OutOfTime! { recorded: total }
}
+ return f"total ${total}, skipped {skipped}, reconcile {reconcile}"
}
In Ritchie, the loop neatly slots over the existing handle block. The handler arms now keep count instead of returning. 16 lines of Ritchie, 27 of TypeScript, and both give the same responses.
Ship it.
Time for a Reckoning
A customer buys four things. We run the TypeScript first, with a 1400 ms budget.
$ CHECKOUT_BUDGET_MS=1400 node checkout.ts
OutOfTime: out of time, $2 recorded
Half a cart. No service failed. Every one responded on time, and every handler did its job, including the one that had to give up. Here is where the 1400 ms went.
The price of b has nothing to do with the price of a, and neither has anything to do with how many are left on the shelf, yet every await made each read wait for the one before it. This cart needs 2400 ms of calls, and a twenty-item cart would need twelve seconds.
Rewiring the TypeScript
We know how to do this. It is what async was for. Our list of demands is short:
- Every read starts at once.
- Writes still happen one at a time, in cart order.
- Every failure rule from before keeps its meaning.
- Nothing is left running after the function has responded.
A good TypeScript programmer reaches for Promise.all first, but then nothing is written until the slowest read in the cart responds. Give line 4 a 1000 ms Pricing call and line 1, ready at 300 ms, waits until 1000 ms to write. The budget runs out at total $3, reconcile 1. Each line has to write as soon as it is ready, in cart order, which means starting reads in one place and awaiting them in another.
const BUDGET_MS = Number(process.env.CHECKOUT_BUDGET_MS);
export async function checkout(skus: string[]): Promise<string> {
const done = new AbortController();
const signal = AbortSignal.any([done.signal, AbortSignal.timeout(BUDGET_MS)]);
let total = 0, skipped = 0, reconcile = 0;
// Start every read now. Await them below, in cart order.
const reads = skus.map((sku) => {
const price = pricing.quote(sku, { signal }).catch((e) => {
if (!(e instanceof HttpError && e.status === 503)) throw e;
return listPrice(sku);
});
const stock = inventory.check(sku, { signal });
price.catch(() => {}); // either can reject while nothing awaits it,
stock.catch(() => {}); // which would end the process
return { price, stock };
});
try {
for (const [i, sku] of skus.entries()) {
try {
const price = await reads[i]!.price;
const stock = await reads[i]!.stock;
if (stock === 0) { skipped += 1; continue; }
try {
await ledger.record(sku, price, { signal });
} catch (e) {
if (e instanceof HttpError) throw e;
reconcile += 1; continue;
}
total += price;
} catch (e) {
if (e instanceof HttpError && e.status === 410) { skipped += 1; continue; }
if (e === signal.reason) throw new OutOfTime(total);
throw e;
}
}
} finally {
done.abort(); // an early exit leaves reads in flight
}
return `total $${total}, skipped ${skipped}, reconcile ${reconcile}`;
}
It works. It responds in 700 ms, and outages, lost responses and deadlines all come out as promised.
Function Colouring. async has been on this function since line one, and every caller of it has been paying the same tax. Now the colour has reached the data. price used to be a number, and it is now a Promise<number> until someone awaits it, so it goes in reads[i]!.price and its type has to be kept in mind wherever it is needed.
The handlers moved. A try around a call used to protect that call. A promise fails where it is awaited, so the fallback for a 503 had to leave the loop and go to a .catch inside a map, while the check for a 410 stayed behind in a second loop. One loop became two, one to start things and one to wait for them, and the rule for a single item of the cart is now spread across both.
Two lines you'd better not miss. Look at price.catch(() => {}) and stock.catch(() => {}). They do nothing, and they are there because a promise that rejects while nothing is awaiting it ends the process. Delete them and a discontinued product on line 3 takes the server down, along with every other customer on it. tsc --strict accepts the program either way.
We wrote the cleanup. An AbortController, a merged signal and a finally now exist only to stop reads that a line further down might no longer want.
That is the state of the art.
The Prestige
Here is the Ritchie checkout from before the loop optimisation.
checkout(String[] skus) -> String {
Decimal total = 0.00
Int skipped, reconcile = 0, 0
for sku in skus {
Decimal price = @Pricing.quote(sku) handle Unavailable! => listPrice(sku)
Int stock = @Inventory.check(sku)
if stock == 0 { skipped += 1; continue }
@Ledger.record(sku, price)
total += price
} handle {
Discontinued! => { skipped += 1; continue }
Unverified! => { reconcile += 1; continue }
Cancelled! => return OutOfTime! { recorded: total }
}
return f"total ${total}, skipped {skipped}, reconcile {reconcile}"
}
Here is everything we are going to do to optimise it.
Nothing.
$ rcrun checkout.ri
total $4.00, skipped 0, reconcile 0
The full cart, in half the time TypeScript spent failing.
That is the same trace our 39 lines of TypeScript produce.
But wait. How does Ritchie know that it can send every price and stock read right away, yet has to send the ledger writes one at a time? That's the Automatic Concurrency feature of Ritchie in action. It does two things that we had to do manually in TypeScript:
Dataflow. A remote call is sent where it is written, and the program waits for its response at the first place that needs to look inside it. @Pricing.quote(sku) and @Inventory.check(sku) need only a sku, and nothing that an earlier line of the cart computes, so the loop sends them ahead for every iteration and all eight reads get dispatched at once. @Ledger.record(sku, price) needs a price, so it has to wait for that response. And price is still a Decimal in the source instead of some futuristic template with a promise.
Effect Tracking. The compiler marks every method that has externally observable effects, such as changing remote state, and every method that calls such a method, all the way up. An unmarked call is a read, and a read can be thrown away: if the program turns out not to need it, it is cancelled and nothing has changed. A marked call cannot be taken back. So it starts only after everything written above it that could stop it has responded, and marked calls go one at a time, in written order.2 That is why the Ledger stays in line, and why a sold-out item does not reach it.
Your handlers did not move either, because a failure takes effect at the statement that made the call, whatever time its response turns up.
To go fast, TypeScript had to change almost half the code. Ritchie did not change at all. It was never slow.
Thank you. You have been a wonderful audience.
Erm, Actually...
This is where someone says, "try language X instead", or "use framework Y". So, we also wrote the fast checkout in Kotlin and Go, in case TypeScript was the problem. It wasn't. Kotlin took 47 lines and Go took 54, and each one had lines that break the program if you leave them out, but that the compiler won't miss.
Yes, we know about Effect, and we know about Encore. It is the best TypeScript has, so let us judge it on what is left: reading it and trusting it.
Here is one iteration of checkout in Encore and Effect, from the point where stock is checked to the point where it is counted.
Effect.gen(function* () {
const { sku, price, stock } = yield* line;
if (stock === 0) { skipped += 1; return; }
const answered = yield* call(() => ledger.record({ sku, price })).pipe(
Effect.as(true),
Effect.catchTag(["Unavailable", "TimeoutError"], () => Effect.succeed(false)),
);
if (answered) total += price;
else reconcile += 1;
}).pipe(Effect.catchTag("Discontinued", () => Effect.sync(() => { skipped += 1; }))),
Here is the same job in Ritchie, handlers included.
Int stock = @Inventory.check(sku)
if stock == 0 { skipped += 1; continue }
@Ledger.record(sku, price)
total += price
} handle {
Discontinued! => { skipped += 1; continue }
Unverified! => { reconcile += 1; continue }
The Ritchie version neatly separates the "happy path" from the error handling. Even if you've never read Ritchie, you can follow it, while the TypeScript-with-frameworks example has turned into an unreadable keyword salad.
Now for trust. Here is every guarantee Ritchie gave us along the way, held up against Encore and Effect.
| Guarantee | Ritchie | Encore + Effect |
|---|---|---|
| An unhandled rejection cannot crash the server | Yes | Yes |
| An unhandled error reaches the caller | Yes | Explicit coding required |
| The compiler knows which errors each call can raise | Yes | Explicit coding required |
| Every call runs within a time budget | Yes, always | Explicit coding required |
| An abandoned read receives a cancellation signal | Yes | Explicit coding required |
| External effects are not observed ahead of time | Yes | Explicit coding required |
| The response waits for every write | Yes | Explicit coding required |
| A failed write can confirm whether nothing was modified | Yes, Unmodified! is built-in | Not built in |
Wherever the right-hand column requires explicit coding, tsc --strict accepts the program with that code left out, and therefore without the guarantee. Ritchie won't save you from every mistake, but its guarantees are not yours to forget.
If you're going to write it in someone else's language3 anyway, try Ritchie. It means business.
This is where you put your foot down and say, "No, we need a batch API instead", and you'd be right. Except, I've seen three very large e-commerce stacks and one of them did the loop. I won't say which one, but I can say that if you made an educated guess, you'd be more wrong than the random sampling chances of ~67%!
Output is written where the same statements run in strict sequence would write it, and when several reads in flight fail, the failure of the one written first is the one that takes effect. Writes currently go one at a time across all services. Further optimisations are scheduled, and they will not require changes to your code.
By the time you're writing Effect.gen and yield*, you're no longer writing the TypeScript everyone knows. Your team has to learn it, agents have to reason through it, and most npm libraries need wrapping before they'll play along. While preparing this article, Opus 5.5 spent about 53,000 reasoning tokens on Effect and Encore, against 19,000 on Ritchie, a language it had never seen. The incumbency you chose TypeScript for is gone.
