Base64 Is Fast Now, Actually

This is a short post.

I was wondering recently, if I had to send a binary file across a text stream to a browser - i.e., embedded in JSON - what would be the fastest way to do that.

Clearly, base64'ing the content is a valid approach and always has a 4/3 overhead.

However, one thought I had is that JS strings are fundamentally just arrays of unsigned 16-bit integers (or []uint16, if you're writing lots of Go, like me). So we can actually just convert any kind of data to a JS string and then encode it again as UTF-8 without risk of loss.

The Thesis

What we do is basically take a Uint8Array ("native bytes"), reinterpret it as a Uint16Array, then convert it to a JS string. The code looks a bit like:

function encode(raw: Uint8Array): string {
  const u16 = new Uint16Array(raw);
  const s = new TextDecoder('utf-16le').decode(u16);
  return JSON.stringify(s);
}

…this actually doesn't work for two reasons:

1. our data might have an odd number of bytes

2. TextDecoder actually generates U+FFFD for bad data, which random binary data will have - it's not actually string data.

Both can be solved - in Node, using Buffer, and in the browser using a few hacks.

The Results

Here is a table of all the results (for a single encode/decode round-trip in ms, but tests run 100s of times). I used an audio file of about 1.4mb, and a zipped version of the same file (~600k).

So: native base64 is stupidly fast. But encoding via UTF-16 string isn't far behind.

To explain the options:

• native base64: this is fromBase64 and friends, available in Node and all browsers from September 2025

• utf-16 in Node: this is the above technique, using Buffer

• utf-16 in browser: we can't use Buffer in the browser, so we have to use TextDecoder with a few hacks

• number array: a baseline of literally converting a Uint8Array to number[] and encoding/decoding it (e.g., [123,0,3,1,255,...])

• atob/btoa: the 'classic' way of doing base64. This is slow because it has to round-trip through as JS string which contains values 0-255. Most polyfills use this approach.

The code to generate this data is here.

Analysis

The UTF-16 approach is interesting, and remarkably fast. It generates a totally valid string, a random excerpt looks like:

"…弼並于忒퍛孾븭䍗伐뾠䫼藸왬愣邲틫違纝Ꟍ牿\udf00왻﫶星멝ꟁ郧葓놹쑘澓燕㺪枢궅᧧澵춢呪垦ൢួ醝⠷銗䇎\udd2c흅蝗ꟛ퍾慙瘝\udc9d縱쯙꾵\udeef篙䶄Ḛ煩忌೷떵䵺업\ude9f輫\udcdc㾺뤻촸㯆孟\udcb9꡸뉺捸蜹躯액ꌀ瑍幘㕢譎뉛ᡦḝ萿힓ܞꪾඞ䣾闧忓槢\udf8e⭖㹠❎⁼ﷳ봝霗טּ棭\ud8dfጚ᭲ꄝ졷憢뙡뷪憓ä䧻弱ᘋᢃ䘶ر哤樹Ꮴ䮙ᔾᎻꩮꐱ趫\ud875摁狃渣ᅝ쿮꣖곷㰰뗊뼥ꎝ᜷\udbcfﴞᮽ轺稯올熽䝂鏅᧵눎᜾ᐋ퉖鋲\udaee쉼⇅뾠奰᳨詻닞굉\ud82dϓ綋놼☳뎭㳉趽畵ꨨ恫ꬬ洕ꈞ㨷鮊ꨋጦ渚陾翿䂼콦爧섺樼ඓ浧乖\ud872༗ḻ࿀徚ꟽ\udfa1疋庨㼖븖⦊⿧…"

But it's also not any smaller than base64. For the two files, the UTF-16 approach is 173% and 154% of the original size, respectively.

Remember, what we're doing is:

• taking a Uint8Array
• reading it as a JS string via Uint16Array
• encoding each code point (or surrogate pair) as UTF-8, so it's valid JSON.

But part of the issue is that most data here ends up having no valid representation in UTF-8, so it ends up being escaped - that's the \udc9d and friends we see above.

And yes, we could start inventing our own binary formats… but that's not the point, the theory is that this must still be valid JSON.

Whereas, base64 is consistently 4/3, or 133% the size of the original.

So What?

This article has a pretty clear outcome, which was literally in the title.

You should probably encode data using the native base64 methods. They're really fast and consistent.

For users on old Chrome, - provide a polyfill maybe for the next year or so, which will be slower, but basically penalize them for not upgrading.

Thanks for reading! 🕺

Major Node Changes

This document is a short list of changes in Node.js' major releases. It does not cover point releases, just e.g., v13, v14 and so on.

v25 (2025)

• v8 14.1
• Supports Uint8Array base64/hex helpers
• Type stripping for TS support enabld by default
  • This does not transform types, you may still need --experimental-transform-types

v24 (2025)

• v8 13.6
  • Adds Float16Array, RegExp.escape
  • Adds explicit resource management, aka, the using keyword
• Improves AsyncLocalStorage (async context tracking) performance
• Modifies the test runner to automatically wait for subtests
• URLPattern is now a global

v23 (2024)

• Better support for require(esm) in more places, for interopability
• Mark --run as stable

v22 (2024)

• v8 12.4
  • Including Array.fromAsync, additional Set methods
• Experimental support for require() on ESM
• Node itself can --run <script> from "package.json"
• Native WebSocket
• Glob functions inside node:fs
• Support for --experimental-transform-types to run TS inside Node

v21 (2023)

• Experimental support (behind a flag) for
  • native WebSocket
  • default ESM support
• Added global navigator object
• v8 11.8, including array groupBy

v20 (2023)

• V8 11.3, including change array by-copy methods such as toSorted
• Experimental permission model (e.g., restrict FS access)
• Marks the test runner as stable

v19 (2022)

• Adds node --watch
• V8 10.7

v18 (2022)

• Adds built-in Fetch API (fetch)
  • Includes Headers, FormData, Blob and so on
  • Adds Web Streams API including ReadableStream and friends
• Adds BroadcastChannel
• Adds experimental test runner
• V8 10.1
  • Includes Array.findLast() and Array.findLastIndex()
• Built-in test runner

v17 (2021)

• V8 9.5

v16 (2021)

• Adds 'timers/promises' API
• V8 9.0
  • Adds the /d flag to regular expressions
• Native support for arm64 on macOS
• Adds AbortController as stable

v15 (2020)

• NPM 7 #35631
• Throw On Unhandled Rejections #33021
  • If you create a Promise without a catch handler, or use a top-level await, a failure will cause your program to crash by default
• V8 8.6
  • Supports new operators &&=, ||=, and ??=

v14 (2020, LTS until 2023-04-30)

• ES Modules no longer generate warnings
• Supports top-level await
• V8 8.1
  • Supports optional chaining, nullish coalescing and friends (the ?., ?? operators)
  • Improved Intl support

v13 (2019)

• Support for ECMAScript modules
  • Includes .mjs extension and setting "type": "module"
• Full ICU support, with support for hundreds of locales

Why Will Wikipedia Wither?

aka: in the age of AI, what is the role of summarizers

Wikipedia is the world's free encyclopedia.

Some definitions: an encyclopedia summarizes knowledge—let's call this primary sources—in a useful, digestable format. And primary sources are, well, primary! Research papers, quotes, police reports, press releases, survey data, photos, stats on Pokémon, medical records, …the list goes on.

So maybe you can see where this is going. 👀

Wikipedia intends to be an unbiased, representative summary of primary source data. (Whether it is or not is a different post, but let's go with this.)

I have this theory that, as we as a society head down the infinite slippery slide of all-knowing AI, anything that 'summarizes'—not just Wikipedia, but also literal journalism—has no utility in a world where an AI can just do this for you.

Star Trek

There's a famous memable scene from Star Trek: The Voyage Home, released in 1986, a few months after I was born. Scotty tries to talk to the computer. Laughable at the time, but today this is something we can just do.

When I think about the future, I have great respect for sci-fi writers of the past: what did they imagine, even and often especially concerning the seemingly inane world-building that purely fills out the scene.

(As a digression, I love that in The Expanse, various scenes feature intermodal containers but IN SPACE. Because why would humanity redesign the standard? 📦🚀)

I won't be the first or last person to think about this, but I think that Star Trek predicted this new world aeons ago (and the newer series basically approach it the same way).

In Star Trek, or other sci-fi canon, the primary way our protagonists—or honestly, average citizens—interact with technology is indirect, via what we now know as LLMs or whatever, that summarize and present information derived from primary sources.

These sources may be "is the ship on fire", but also "what is the population of planet XYZ", or "who was the victor in the Great War of 2775".

We don't see our stars sit around reading blog posts trying to glean some insight into the culture of a new race they're meeting, not just because it'd make for pretty lackluster TV, but because this is a 'solved problem' in their universe.

Deep Implications

Let's apply this to today's world, or say the world we want to build given the advent of LLMs (and LLMs masquerading as "agentic AI").

I think it basically tells us that the web is dying.

This is a big take. My job at Google for years was to promote it.

But even in the early days of Gemini or ChatGPT, I found that the best use of AI was basically just to 'summarize' some content, news or otherwise, that was otherwise covered in ads and cookie notices. And while I do think content sites have realized their hubris here, and generally pulled back on some of the noise, I don't see a world where this business model works.

But to take this point to its logical extremes, why do say, news sites even exist? I'm aware this is a horrific idea—we're killing off journalism—but at its core, journalism is reporting on what happened, i.e., primary sources.

Instead, why not simply ask an all-knowing AI to summarize those same primary sources? Isn't that what journalists and Wikipedia do?

Again, it goes without saying that this (as it stands today) is a terrible idea:

• journalists often (but not always) collect/prepare primary sources: they conduct interviews, go on-site to take photos, investigate and reveal hidden data, etc

• the bias of journalists is (sometimes) known; for example, I don't believe articles on The Australian (despite being behind a paywall) are written with good intentions; similarly, the ABC often promotes deeply unscientific views in the name of showing 'both sides'

• more fundamentally, what is a primary source—how can an AI identify fake data saying that 90% of students are secretly furries or that vaccines cause autism

Back to my point about the web: Google is diving head-first into the death of the web, because I can answer my queries with zero-click searches—that's even without using Gemini explicitly. And of course, ChatGPT was never a search engine to begin with, so every answer it gave you was zero-click.

So why have the results at all?

Critical Thinking

I haven't thought this out too much—I'm going to write another view on what AI means for education, especially for the sort of future I want my young kids to experience.

But right now, in 2025, some students live in the ludicrous world you already know about: they press a button to receive an essay, which is submitted to a teacher who might just pass it back to another AI to grade it.

One naïve interpretation here is that this may weed out performative assessments. Is the kind of counter-intuitive 'benefit' here we can dismiss with topics that students don't actually want to learn? Is this today's calculator? (Of course, this assumes they want to learn anything.)

Primary Sources

I think we're moving towards a world where the importance of primary sources, content, whatever, is raised.

This blog post is itself a primary source—it's an opinion, which arguably still counts. And LLMs will happily slurp it up probably minutes after I post it, just like every bit of content out there.

And cynically, you could twist my argument here to mean that everyone should be a "content creator".

But I actually kind of mean that. We should all be collecting (and publishing) small data.

If AIs are free, and they are effectively all-knowing (again, big ifs) then the benefit here is that they can identify new, novel data or connect the dots between data in interesting ways. The average research paper is read by zero people (rounded down).

Is the next big thing going to be the idea of collecting new and novel data, or at least working out how to best and most effectively publish your own discoveries?

Will the new journalist class not publish 'articles' as we know now, but purely publish their primary discoveries in as plain-text as possible for a LLM to consume for it to surface to the world?

Discovery

Going back to Star Trek v. Wikipedia (2025), one contrasting issue with how we imagine people in the future interact with content is that of discovery.

A better question is where are the doom-scollers in the Star Trek universe? Again, this doesn't make for great content, but is Boimler sitting in his bunk reading a book (AI-generated or not), or doom-scrolling his TikTok feed?

And zero-click searches are great for answers, but are seemingly not great for discovering more. (To be fair, maybe that will change.) But for better or worse, Wikipedia is curated, and it has novel things like headings that I can scan to find out whether I really want to dig into the 'controvery' section for my favorite actor.

There's also the concern that an agent acting on my behalf will reinforce my biasies. If I only want to know if my favorite actors own a dog, every question will start reporting that in favor of something that pushes me off that path.

Parting Thoughts

I don't know why I wanted to write this post. I think I'm trying to imagine the world I want, given the constraints—given where we seem to be heading.

Do search engines survive this change? Does journalism survive? Does it need to?

These are all interesting questions I don't have the answer to. Anyway, bye 👋

All Browsers Get This Wrong

We found a bug in Shadow DOM that's strangely consistent across Firefox, Safari and Chrome. And this bug is strange: it's not actually a user-facing issue, but rather, something the developer tools across each browser just gets wrong. 🤯

Background

I'm a huge fan of Web Components, despite their various downsides. Part of this was my time at Google: I was paid to believe in them, and it's hard to get out of that habit.

In building my startup Gumnut Dev (we make your forms collaborative), we found something odd.

Our use-case for WCs is a bit different than normal. We provide an element <gumnut-text> which drops-in to replace your <input> and <textarea> elements—but instead of being plain old editors, this editor now connects you to other users on the same page. See a gif:

Sounds great. This element isn't styled by default, because we're a platform—we don't have an opinion on your styles.

But of course, it's been tricky to get it right: read on!

Issue

WCs typically use Shadow DOM, which has a bit of an odd quirk.

The display: ... CSS value of your host element (i.e., <gumnut-text>) is used as the top-level display: ... property of the Shadow DOM.

Who cares, you ask? Well, we care, because if you as a user of this element were to accidentally set the <gumnut-text> element to display: inline... this happens:

Now, who is going to do this, you ask? Well, we're not sure, but one thing you learn shipping what is fundamentally an API to your users: you want to prevent them from "holding it wrong", because if they can, they will. 🫠

My Learning

I always thought this ability to override values was a limitation or a 'dumb choice' of WCs. You have this element which doesn't really act independently because your end-users can muck with it.

However, I was wrong. 🥺

When you style your Shadow DOM, you create style which looks like this and can reference the special :host selector. This selector refers to "the container", so in our case, it styles <gumnut-text. Something like this:

:host {
  display: inline-block;
}

What I didn't know is that if you set !important on this rule, nothing can overwrite it. This :host declaration always wins, even over 'external' style, the style="..." attribute, even if that value is also set to !important. And this is fundamentally counter-intuitive to my view of CSS priority.

So let's imagine I have an element like this (SD isn't defined like this, but let's pretend):

<gumnut-text style="display: inline !important">
  ::shadow-root
    <style>
      :host {
        display: inline-block !important;
      }
    </style>

…your resolved display value will be inline-block. Huzzah!

And of course, this applies to all properties; not just display: you could control your element's border, or padding, or transform.

Where Browsers Are Wrong

So the key of this post is that my uneducated view is actually not dissimilar to literally every browser's view, as they all have a bug in explaining what happens here. And this is problematic, because it masks the behavior—it's not discoverable!

Let's look at what Chrome says:

Firefox and Safari are similar. They all know the final resolved value, but can't explain how they got there.

Why Do I Care?

Well, you care because this greatly expands your ability as an API author to ship components that you control. WCs are a perfect fit for shippable components, because you don't have to rely on the user also using React, or Vue, or whatever framework of the week… they can just work regardless of your target.

And even though we at Gumnut Dev also ship React components wrapping up our WCs, those components still expose styling/etc attributes that apply to the internal <gumnut-text>. So without this control, it would be just as easy to shoot yourself in the foot and "hold it wrong", even though users of React ostensibly have a layer of abstraction in the way.

Thanks for reading! If you're interested in drop-in collaboration (no more overwriting each other's work), audit logs, history through character-level attribution—and having your forms work like they're from the future, getting out of the way of your actual business—do say hello. ♥️

Attributions

And finally, thanks to bram.us for clarifying the spec on how this should work. Cheers!

Collaboration, Now!

Update: If you're in Sydney in July 2025, join our hackathon!

I've a bold claim to make. I think the web is stuck, stagnant, immovable, … more synonyms. 🛑

We're stuck in, fundamentally, a React-pinned era. Around ~2018 or so, React had the complete suite: functional components and hooks. And modern app development, whether you like it or not, is largely inspired by that kind of idiom—whether you're using actual React or one of the many libraries that try to be like React. 🤯

Instead of making the web better, we as developers are just trimming the hedge of its walled garden. It's not growing, changing or evolving. 🧱

Multi-User Is Not Collaboration

Let's get right to it. I've co-founded a startup called Gumnut Dev because we want to bring the web forward into the future—and for us, that means collaboration.

Our problem statement—more specific than 'the web is stagnating'—goes something like this:

Your product is designed for multiple users—but can they actually work together? Or are they just digitally bumping shoulders and passing like ships in the night?

Gumnut Dev enables inline collaboration within your existing forms, with no database changes. Increase productivity between your real users and lets AI agents contribute natively. And we store history over time, down to the keystroke, of who did what.

Here's a little preview:

We're not solving every problem with the web. Maybe later. But for now, we're solving collaboration for your SaaS/product/web application 💖.

So why are we founding the startup? It behooves us to start with…

A History Lesson 📜

Google Docs released in … let me check … two-thousand and six. That's nearly twenty years ago.

And so as software engineers, as product managers, even as users of a product: we all know collaboration is possible. But we look at Google Docs, or Notion, or Miro, or… any one of the number of collaboration tools, and somehow we believe they're special.

And so, collaboration outside these experiences is totally alien to the average user. Why?

Cost/Benefit 💸

Our big thesis is two-fold. One is the broad React-stagnation problem. The modern, app-like web, is stagnant.

The other is that the cost/benefit isn't there. Why would I spend time adding something that isn't really core to my product? I don't want to have to pivot to using a different database, or running a websocket for real-time editing, or—the list goes on.

And if you do want collaboration, you have to ask your CTO/management… can we get multiplayer content editing superpowers users expect in our own app without spending the next 12 months building something that doesn't meet expectations?

So of course, that's what got us thinking. 🤔

The Right DX 🧑‍💻

Collaboration is a relatively solved problem. Technically, academically—there are solutions. CRDTs, or Operational Transforms, and products that implement them—they exist. And they've come a long way. CRDTs, for example, were classically overlooked because they were 'too heavy'. Smarter people than me have worked out that they can be incredibly performant.

This is all interesting. But these are experiments at best: they're not a product you can just use.

We at Gumnut Dev are building a product: a new paradigm of how you can just add these things to your existing sites, web applications, and SaaS'es.

And ironically, despite my bellyaching, using Gumnut Dev is just a React library you drop in:

function YourForm() {
  // models other form libraries, but with collaboration!
  const s = useGumnutDoc({ getToken, docId });

  return <div>
    <label>Edit AI Prompt</label>
    <GumnutText control={s.control} name="prompt" multiline style={...} />
    <GumnutData
      control={s.control}
      name="enabled"
      render={(arg) => (
        <div>
          <label>Enabled</label>
          <input type="checkbox" {...arg.field} />
        </div>
      )}
    />
  </div>;
}

Okay, there's a tiny bit more setup, but we're talking hours, not days or weeks, to get this sorcery working. 🎩

Some Internals

This is all well and good—Sam, you're pitching me a startup, I get it. But I assume my audience is technical enough to want to know a little bit more before diving in.

I think the best way to represent what do do under the hood is with a little video.

The way to think of what we do is: we get out of the way of your existing database, and host an editing session—think of it like a git branch—where people can work together.

Once your editing is complete, Gumnut orchestrates a simultaneous commit back to your database and a full-history snapshot witten back to Gumnut. Your database doesn't know or care that the work was prepared in our "temporary collaboration dimension"; it just sees the new data, ready to be used.

Implications

The core design is pretty—I don't want to say simple, because what Gumnut does is complex, and you should pay us to do it for you (no bias here).

But now that we help you edit, you can think of a user editing something in a boring old HTML form as not just this transient thing that happens in their browser, but something that has a life of its own.

1. Collaboration

The obvious implication, which I introduced at the top, is collaboration. You're working on something together. And who gets to work together, that's something we help you configure (via JWTs and fairly standard authorization practices).

Frankly, this stops your users leaving to go to a platform like Google Docs to get their work done. You want users to be sticky, more engaged, and expecting more from your site—so you're easier to use than your competitors. Ask yourself: how often do people get off your platform because the only way they can be productive is with an external tool?

2. Review and approval

Because an edit session is no longer just "in someone's browser", why not ask/demand/expect that your content is reviewed before it's saved back to your database? Gumnut could email or contact a list of reviewers—just like how we write code—and ask for their feedback before it allows you to save. 💾

3. History

Every time you commit, your product's database updates. That's the way it should be—your database is for running your business.

But Gumnut can keep track of what you changed over time. And this is an incredibly important feature that most SaaS'es overlook, at least initially: you want, nay, you need, a proper audit trail.

And if you've not thought about this, and you have compliance risk, whew! This is the only part of this post which is trying to elicit 'fear', which is one way to promote a product.

But it's also important. 💭

Gumnut stores keystroke-level attribution every time you commit: you know who changed what, and when, and you can go back to that later. You might load it via API, or inline in your own forms in a "history" mode—but the important part is that we store it for you for free, so when shit hits the fan, you can find out how you got there.

And again, this is all without modifying your existing database solution.

4. AI Agents

AI is a bit of an orthogonal dimension. But right now, a regular SaaS with a multitude of forms doesn't have a great way to have AI help you. Instead, AI agents can be collaborative users just like anyone else on your site—ask them to fix spelling mistakes, do rewrites, or just work with you to achieve a goal.

Here's a demo of something simple, just coming along and cleaning up spelling mistakes:

And because we're storing history—we know what the AI added versus anyone else. So if you think the AI has hallucinated, well, you can find out exactly what parts you can cut out. 🔪

5. More?

We have a lot more ideas, but then this blog post would go on forever. 😂

But we fundamentally believe Gumnut is a new way of thinking about working together on the web—one that stays away from your existing choices in a good way—add us to your platform to make your product better.

What Now?

Why are we building this startup? We want to move the web forward. And for me, that piece is collaboration—why shouldn't it come cheaply, with history and AI agent support built-in? It's crazy to me that we are stuck in this rut, using amazing technologies all around the place but being totally unable to integrate it in 'regular' products.

To my original thesis: there's other parts of the web that need improvement, too—we'll come back to them once our first product is wildly successful. 😂

So we're eager for you to try it out, book a demo, all those things—the "like and subscribe" of the SaaS world.

👉 Hit us up at https://gumnut.dev. Book a demo, or join our update list.

Thanks for reading! You're officially ahead of 99% of the internet. 💝

Post-Request/Response Apps

Serverless or monolithic/'serverful' architectures are often presented as sides of the same coin: they're both just alternative ways to serve synchronous requests, for example, a HTTP server serving content, or handling API requests publicly or internally.

But this is a naïve viewpoint, and we as developers now almost see 'serverless-like' development as the silver bullet for potentially enormous scalability, throwing away the imperative nature of writing long-lived server code. We've collectively forgotten how to write servers!

(Remember that serverless is broadly defined as computing which scales easily, but with no reliable state—every request may be handled by a new process, which is orthogonal to a long-lived server.)

Of course, it's fairly easy to list the pros and cons of serverless vs monolith through the lens of synchronous requests only: many articles do. But this doesn't consider an application, system, whatever you're doing, holistically—you're focusing only on the pointy end, how your components interact.

This article will talk through why serverless adds needless complexity, and provide actual concrete examples of how, where and why to adopt monolithic—importantly, horizontally scalable monolithic—approaches to backend design. Read on. 🥳

Background on Serverless vs Other Approaches

Again, serverless is computing that scales easily, with the tradeoff that it's stateless. (And it can be great for work that's actually stateless!)

We see fairly broad implementations of serverless:

• you have Cloudflare Workers, which pushes your code right to the edge, and has amazing performance properties
• AWS Lambda is the original, but it really embodies the above definition: yes, it scales, but it's slow to start up and each instance only handles one request at once (which is painful when you're probably further I/O bound within the Lambda)
• Google's Cloud Functions is a nice middle ground, as its v2 supports concurrency

All of these can be wired up to serving user requests, webhooks, callbacks, whatever (the world is HTTP, after all). It's also worth honing in on what 'stateless' actually means—every request handled by your serverless code may be in a fresh VM. (Although in reality, most providers reuse VMs for a short time, or this is configurable—restarting is costly for them too.)

On the other hand, we have non-serverless code, where a VM's lifetime is much longer (it won't live forever, but who does), and typically can serve many requests in parallel. Environments that run this code often (but not always) allow you to scale horizontally, allowing you to run a configurable number of instances which are used based on the requestor's geolocation, server load, even randomly, or perhaps with a session affinity cookie/header.

• AWS has Fargate, which is their solution for "just let me scale VMs please"
• fly.io provides these options, as it provides a single anycast address plus HTTPS certs for any service you run—doing intelligent routing and running code worldwide
• your suggestion here?

Thesis

My thesis is that serverless' biggest trade-off is it being stateless. Because running code this way is intentionally unreliable, serverless requires you to express your state externally: at best in a database, and at worse as the machniations of a complex system with queues, events and state offloaded to your cloud provider's… "primitives".

We, as software engineers, already have a great way to hold state: in memory.

And the advent of serverless has encouraged us to think of all possible serving options as analogies to serverless, where their only job is to serve requests as fast as possible with the existential dread that the process may be evicted at any point.

We, as backend developers, have collectively forgotten how to write code that considers the current process' interaction with a client to be a long-term arrangement. And, to be fair, this isn't guaranteed either, short of using a monolith (that is, O(1) server, rather than O(n)) servers): the internet is a hectic place, and two HTTP requests made by the same client might not be routed the same way.

The Alternative

So, Sam, you say that serverless is poor, but then disregard that point by telling me that we should either use an O(1) monolith or give up because HTTP requests will route oddly. What's your point?

Well, the point is that there's a number of patterns that blow serverless's complexity right up, and we should actively be seeking out imperative solutions (even if a bit tricky) rather than just adding more serverless: those "primitives" I mentioned earlier.

To quote a developer I mostly admire:

The solution to serverless always looks like more serverless.

…the meaning here being that serverless taints your thinking: it's always one more construct, rather than just being able to write imperative code.

And while that above explanation sounds good, it's still abstract. There's two main points you need to consider when architecting something that encapsulates long-term state.

1. What types of tasks are good candidates. This is the concrete 🏗️ example part—what are the goals with serverless that you keep thinking, if only I could bend over backwards even more…

2. How you can ensure that an end-user can access that state. This is subtle, but important, because of the HTTP request routing above. If a horizontal monolith is taking on some task, but a client (website, app, or even other service) no longer has affinity to that target (whatever reason), how do you 'join' again?

1. Serverless Sucks For

Medium-Running Tasks

Let's say you have a user-initiated batch task: something that you'd love to do a in single HTTP request from a client, but which takes just a bit too long, say a data conversion or an export task. And you're thinking—oh no, do I need to set up queues, event busses, more infrastructure just to do this thing? Think a few minutes' long, where you'd like to give user feedback.

Serverless tends to make this hard because:

• serverless functions tend to have hard execution limits (although they are going up these days)
• But they are modelled entirely as request/response beasts—yes, you could have the function emit status update logs you consume elsewhere, but fundamentally they're not designed to give intermediate feedback.

With long-running instances, we can have the ability to simply do work for a long period of time, disconnected from the request/response cycle. What a concept! 🤯

You might architect this through a task that subscribes to a database (used like a queue), enacts a lock on a task, and undertakes it. If the job dies, the lock expires and you pick up the task again.

Or you could start these tasks in direct response to a user's network request, and your frontend simply undertakes some CPU-bound work for a while before its result chills in memory for the user, or is pushed back via a socket.

Single-Homed Logic

Think of Google Docs as a good example. Each document has a unique ID and is fundamentally brought into memory and run somewhere when it is opened by any number of users. It exists in a database, yes, but a client 'joins' a single process which manages its OT logic.

In a serverless land… oh wow. This is almost untenable; you could do it by having each operation (a keystroke, pasting text) talk to any serverless function, open a shared database, and perform an atomic operation on that database. Simultaneously, the client is polling or fetching changes from that same database, so it can keep in sync with other clients.

This really rolls up two really tricky things for serverless:

• a place to run long-term imperative code over time without the risk of ☠️
• global locks, or a way to say "this instance is the host" of the document 🔒🎯

And the same idea could apply to more complex applications, for example, building a Slack or Discord-like service might have each 'server' run its logic imperatively on a unique machine.

🌈 Shameless Plug 🌈 This is one of the use-cases of locksrv, my offering that can provides fast yet global locking of unique IDs.

But also, you can use Cloudflare's Durable Objects for this purpose, too.

To be fair, this problem doesn't need global locks—each document ID could itself embed a home region (where most of its users are), and then a lookup to a fast key/value store like Dynamo could tell you who's currently the boss.

Agent Behavior

Not that kind of agent 🕴️.

I've danced around this point, but one of the approaches we've lost when building serverless is the idea that your interaction with a website, app, whatever, is actually both happening in the client and on the server. And instead of just connecting to a grabbag of lambda helpers, we could connect to a task, the agent, which is dedicated to helping us.

Now, an agent here might not map 1:1 to each e.g., open browser tab—maybe it's an agent per sign-in, so the same auth details get help from the same VM. Maybe it's an agent or pool of agents per company using your premium SaaS.

Why does an agent help you? It acts as your generalized bridge into a hosted part of any product, doing things on behalf of the user. Now, that's abstract, I confess, but…imagine a world where:

• you're using AWS, and you're recieving some update over SQS or an event bus
• these services don't have a client-facing version, i.e., they can't be directly wired to an end user
• it's totally possible to rig up serverless code to itself be called on an event, which puts something into a database, which a user polls, but…you see where I'm going here.

Instead, have an agent working on behalf of the user which when instructed, listens to SQS and identifies events for its client. It could even fall back to polling a database or checking logs if no answer arrives in time. It then pushes the update over a user's open socket, or stores it in local memory until the user is able to read the answer—if the user 'disconnects' for a minute, the agent stays awake and ready for a short timeout!

What about a simpler example? A user could make a complex SQL or SQL-like query, where the results are complex to compute. While a backend can quickly return a small number of responses, an agent could continue preparing more—with the assumption that another request will arrive soon after for additional results.

The point being here is that dances like this should be compartmentalized inside simple, imperative code rather than a million lines of config orchestrating ostensibly cheap 'on-demand' infrastructure. 🔥

2. Accessing That State; or, HTTP is ephemeral

However, back to my earlier issue: if HTTP requests route anywhere—isn't this just serverless all over again?—what's even the point of doing this work? 🤔🤔🤔

Again, this could be solved by an actual monolith, where you only have a single server. But that isn't the point of this post.

Socket

One way to guarantee that the user will get access to whatever imperative code is to actively pin the connection to a remote server, literally via a long-running connection: a WebSocket. (In the future, this will include WebTransport, but it's not widely available yet. You could also use Server-Sent Events, but this is only ½ of the solution.)

This punches a hole through any kind of odd routing or concern about affinity. Your client can directly connect to a server which might do work for you.

There's caveats: sockets are good for the 'agent' model, where you only have O(1) connection per-tab (or perhaps per service worker, but that's a whole other blog post). And while the point of this post is that you can have long-lived code with horizontal scaling, if you don't have enough load to be distributed evenly, then one server VM may end up randomly being assigned too many socket connections.

Pedants might note that AWS, for example, has a serverless WebSocket solution. But it's fundamentally an antipattern: it removes all benefits of WebSocket, instead mapping it back to request/response. It gives none of the benefits of a long-lived socket.

HTTP or request/response

We could attempt to emulate a socket-style experience in HTTP with pure hope—modern HTTP/2+ is designed to use the same 'connection' for many requests. But we can't guarantee that, and imagine a network drop: even our reliable WebSocket can disconnect and need to retry.

There's a couple of approaches here, some of which I've already alluded to:

• Most cloud providers allow for session affinity (via cookie, their front-ends will route you) or targeting specific VMs.

  AWS has "sticky sessions", Google has affinity, Fly.io allows targeting a specific instance—any client in a relationship with a backend can retry its requests with this custom header. If one of your servers sees a request for its peer—redirect it that way!

• Using serverless-style front-ends which themselves perform affinity routing to a further layer based on your own code. This can be fairly stateless, and less 'obvious' to evil actors—the affinity token might be encrypted or actually be a lookup to a global lock service (again, 🌈 let me know if I can help 🌈).

Best Effort

Finally, the 'agent' example above doesn't actually care that much about session affinity—or, at least, you can leverage it when it works (which, again, is often in the world of HTTP/2+) and just accept when it doesn't as a "cost of doing business".

Think of it like a boring old cache implemented in memory, but instead of purely caching some, e.g., database rows, you're actually 'caching' some running code on behalf of a user assuming that you'll see them again. And if you don't see them again, there's no harm, the code stops after a timeout; the client will retry and hit another process which starts the agent anew.

Discussion

What is Serverless good for? I want to be clear, this is not (entirely) a hit piece. But it should be used sparingly, for reasons like:

• glue code between other services which need to trigger a callback—this is literally the origin of it at AWS
• short CPU-bound work that can be surprisingly unexpected for your service—if you say, batch convert images for the public, maybe you can do it here
• as a stateless replacement for awkward configuration languages—e.g., Cloudflare/CloudFront Workers can set headers or wrap up tricky results
• small/underutilized services where running 24/7 might be costly—although platforms like Fly.io and Cloud Run can actually mitigate that, by giving you far more control over your VM's start and stop times.

I think the complexity of real servers (or VMs, whatever) can also be a lot for new developers. I get that. Firebase Functions (just wrapped Google Cloud Functions), for example, is pitched at a low/no-code world: you largely have a static site and just need to slowly add some dynamic logic. As long as your model fits in that request/response model, sure—but don't let the tool limit your thinking that even toy apps can't or don't need a long-lived component.

Finishing Up

I'll say it again: I've seen serverless being used because it's viewed as this 'silver bullet' for one day landing on the front page of Hacker News. And that it's "all people know these days"—just using React as a stack, which is almost just an attempt to make your job posting seem sexy at this point—so of course you'll mention the buzzword when hiring. (I would!)

So while serverless can have its place, it represents the unfortunate baseline that other approaches tend to be measured against in common discussion. And the reality is that it brings every other possible approach down to its level.

Cheers 👋

I run a course called Polaris for upcoming leaders and CTOs of tech startups in Sydney, Australia, where I have opinions like this. I'm also available for consulting if you'd like to pay me to rephrase the content in this post especially for your company. 💸

Node.js can run TypeScript

This is a fairly quick post, but it's impactful if you use Node.js.

Node.js can now just run TypeScript locally, without needing tsx or a build step.

How

Node v22 has added an experimental flag, --experimental-transform-types. This supercedes a previous strip flag, because it supports code-based TypeScript features like enum. (Maybe there's some features still missing, but it's "good enough" for now.)

To run a TypeScript file, you can now:

$ node --experimental-transform-types file.ts

Just like that. 🤯

Configure Your Shell

Instead of passing the flag around everywhere, you can configure your environment to always do it. Inside your ".bashrc", ".zshrc", or whatever, add:

export NODE_OPTIONS="--experimental-transform-types --disable-warning=ExperimentalWarning"

This means that every invocation of Node will transform TypeScript files, and it'll muffle the egregious warning that was being dumped in your terminal.

Configure Your Projects

This is tricky. If you write a "package.json" file with scripts, you can't assume all users might have these flags configured.

You can add to scripts:

{
  "name": "yourproject",
  "scripts": {
    "test": "NODE_OPTIONS='--experimental-transform-types --disable-warning=ExperimentalWarning' node --test **/*test.ts",
  }
}

This is a bit gross, but means that anyone with a sufficiently high version of Node will get the feature.

Note that the above sample also uses Node.js' built-in test runner, which is also one of the greatest things since sliced bread. 🔪🍞

Promotion

At some point, this flag will probably be enabled by default. Will it be in Node 23, or 24? Who knows. Watch this space.

Module Benefits

While subtle, the other huge benefit of built-in TypeScript support is that code like this now works:

import { Worker } from 'node:worker_threads';

const x = new Worker('./other-module.ts');
const other = await import('./other.ts');

i.e., you can import dependant code even if it's written in TypeScript.

This is one of those things that should never have been hard, and now it's just solved—it was previously difficult to both transpile and for a tool like tsx to handle.

Fin

Short post! Enjoy. 💞

Kuto, a reverse JS bundler

Kuto is a novel approach to shipping code on the web. It lets you re-use code a client already has for shipping updates.

For a 'real-world' site with ~3mb of JS, updating the React dependency resulted in:

• 71% smaller download
• 28% faster start time (on a ~5yo old phone, a Pixel 3).

…vs a single bundle, or any case where all the code is invalidated.

Note that Kuto works really well on the final ESM bundles of real sites or apps, but probably not libraries themselves, even though Kuto's output will be valid. Kuto also works as a predictable 'chunk' generator for large bundles.

If this is interesting to you—do you have too much JavaScript?—then do the thing, and do a Kuto on your code. (Is Kuto a verb? Who knows. I'm trying it out.) ✂️

How does it work?

Instead of focusing on minifying output or anything idempotent, Kuto takes a different route.

1. On the first build:

   • Kuto splits source JS into a 'main' part, and a normally larger 'corpus' of code which has no side effects.
   • This corpus can be cached forever, and a hashed timestamp is included in its output name.

2. On every further build:

   • Kuto still splits out the source JS
   • It identifies code from any existing corpus that can be used to 'satisfy' the source JS
     • Each corpus will either stay the same or shrink as functions, statements etc change
   • Any code that cannot be satisfied is put into a brand new corpus, which can also be cached forever.

This is a little complicated. Here's a gif video:

After each build, you're likely to generate another corpus with changed code. (This will eventually be an issue with fragmentation, more on this later.)

Why does it work?

Each corpus, once fetched by a client, can be cached forever. However, on every build, that corpus may shrink in size. New clients will get the smaller version. (Kuto's corpuses have a hashed timestamp, and you do have to set up your webserver to send the right headers here).

But…this breaks all we know about caching responses on the web! I've changed an immutable file! 🤯

The result is that older clients will have bigger files, and newer clients will have smaller ones, even for the same filename. But that bigger file simply has now-deprecated code. Kuto's primary thesis is that disk I/O to load a slightly bigger file than you need is faster than compling anew.

(Note that at least v8-based browsers cache the bytecode of the source, which provides the speed benefit. If you were compiling anew every time, Kuto wouldn't help.)

Aside the remarkably bonkers way this leverages your browser, Kuto also basically performs code-splitting in a completely predictable, useful and automated fashion. Other bundlers either require you to:

• (not codesplit an output bundle at all)
• explicitly mark dependencies to be put into their own bundle
• put code in bundles on (effectively) random boundaries, just trying to restrict the size of each 'chunk'.

No really, how does it work?

The above explanation was fairly high-level. At a lower level, Kuto looks for code with no side effects to include in its corpuses, and it uses circular dependencies to ensure they're safe to call.

No Side Effects

Turns out, defining a function has no side effects. No, really! The definition of a function does nothing except creates a variable:

function foo() {
  console.info(`Side effect`);
}

Since foo isn't actually called, and we declare it in a module scope, nothing happens. Until we run foo, it might as well be:

function foo() {
  // Blah blah blah blah, I'm Schrödinger's function
}

Kuto takes this theory to the extreme, putting classes into the same form, and even arbitrary statements. We *hand wave* can hoist statements to be within a function.

Circular Dependencies

Each corpus contains silo'ed^ functions which reference back to the main file in order to work out their dependencies. A good way to see this is to check out Kuto itself and run its "./release.sh" script, which builds Kuto itself this way.

For a trivial site that appends a custom element to your page, where the custom element has changed and been rebuilt, this might look like:

// main.js
import { _1 } from './main.kt-abc.js';
import { _2 } from './main.kt-def.js';
_1();
export { _2 };

// main.kt-abc.js
import { _2 } from './main.js';
export var _1 = function setupSite() {
  const element = new _2();
  document.body.append(element);
}

// main.kt-def.js
export var _2 = class MyElement extends HTMLElement { /* ... */ };

This all looks awkward…and it is, but the output isn't really meant for human consumption, but we benefit from ESM's "seen as a bug" feature of circular dependencies.

^Kuto will in future reference between corpuses

Should I use this?

Maybe!

Kuto is new, and while the science says it works, it's a bit weird. And as I've mentioned above, it works really well on:

• single bundle output sites
• that have a large JS bundle (maybe >1mb?)
• …which are made up of lots of top-level ESM code, such as functions and classes

You will need to:

• use a regular bundler first
• keep or have access to your old build artifacts—Kuto doesn't know what you already shipped by magic 🪄
• trade off a slightly larger first load for a better update experience

The other issue with this is that more and more browsers are moving to a world where cache is regularly evicted. If your visitors don't have your site cached, then Kuto is pointless—every load is slightly more expensive for an update that never happens. YMMV.

Regardless, the tool emits a few statistics, including how much overhead the initial load costing you, and what % of code is able to be identifed as having "no side effects" and put into a corpus. And to be clear, running Kuto on tiny codebases has no benefit—the 'cost' of parsing a few kb of JS is trivial, even for potato phones. 🥔

So you can experiment and see if it works for you. My view is that Kuto will help for enterprise apps (because the JS is bloated, and no-one really cares) or social media (because power users come so often).

Fragmentation

Kuto generates multiple files over time. Right now, it actually only uses the top 4 (by size) previous bundles, although this is configurable by flag. This is…not very good, and I'm yet to come up with a good automatic metric as to when to 'clean up' vs 're-use'.

Consider this though: if you just don't provide Kuto with historic bundles, it… obviously can't use them. So you can decide whether that typo fix generating a 100-byte file is worth it for the next build.

Why Only 28% Faster?

Ignoring some of the possible downsides, there's a big question for me at play. My test case above showed 71% reduction in size, but only 28% increase in speed. 🤔

I have a suspicion that v8's assembly of a bunch of module code is still quite costly. Yes, it's great that huge chunks of static code can be outsourced and cached forever, but in the end, your website still needs to assemble it all together.

An Ask

I would love to hear from you if Kuto makes a material difference to the way you bundle and update your code, even in just a theoretical test environment. Please feel free to contact me, including filing a GitHub issue, if you can give me some sweet, sweet numbers.

Thanks

Thanks for reading! Kuto has been incredibly interesting to build, yet honestly it's only taken me a few days of full-time engineering to make it work. It's been an idea I've been noodling on for a few years, and I'm really proud to have it come to fruition. 🍇

CJS Equivalency

I've been working on bundler-like things and I've thought again about the classic CJS vs ESM interop issue. It occurs to me that one way to transform CJS to ESM is to treat each CJS file as a 'builder'. This isn't bundling, but perhaps a step on the way, or for a serving library which purely provides a transform.

Example

Here's a reductive example. We have a CJS file which has both a top-level and lazy import:

const other = require("./other.js");
module.exports.performAction = () => {
  const lazy = require("lazy");
  return other.helper(lazy);
};

Can be thought of as, with the original code largely unchanged in internalBuild:

import otherBuild from "./other.js";
import lazyBuild from "./node_modules/lazy/index.js";

const builders = {
  other: otherBuild,
  lazy: lazyBuild,
};
const require = (name) => builders[name]();

function internalBuild(module) {
  const other = require("other");
  module.exports.performAction = () => {
    const lazy = require("lazy");
    return other.helper(lazy);
  };
}

let cache;
export function build() {
  if (!cache) {
    cache = { exports };
    internalBuild(cache);
  }
  return cache.exports;
}

In practice, you'd autogenerate this code. Watch this space.

Note that cache is important as otherwise we won't get singleton behavior. Each import or require of the same file should return the same object—it's only evaluated once.

What's missing

1. The final user of the CJS file (whether browser, or a real ESM) needs to invoke its default export. So you can't just rewrite the CJS—the caller needs to know, too.

2. The builder is still exposed on default, and you can't treat individual export properties as special—CJS is always just exporting 'a singleton'.

3. Dynamic require() statements don't have a good mapping here. The equivalent in ESM works because it has to be async, and require isn't going to suddenly start supporting that now. Anyway, no serious bundler supports this either.

4. Going back from CJS to ESM (i.e., a require() that points to a ES Module) could work the same way (moving it inside a builder), but now some of the seams are breaking a bit, because the point of ESM is that we can be purists about it and not rewrite most of that code.

Why this works

I think my initial instinct was to try to convert each require call to be dynamic, somehow. Instead, we can basically precalculate the graph in an ESM-style without actually executing any CJS code. Importing a file which has been transformed will evaluate none of the original code, but set it up in a way that it's ready to be.

Why this post exists

Why not. You've read it. Enjoy!

December Tech Vibe Check

It's the end of 2023. This isn't a "year in review", just some musings about what's been going on recently.

Read on to find out more about:

• What I'm doing in the Cloud
• What open-source code I'm publishing
• Some business plans and musings.

Cloud Tech Stack

There's been some cool updates in the way I build projects.

Cloud Run

I bit the bullet and moved this blog over to Cloud Run with all the bells and whistles. This is fine, but I end up paying for a myriad of various services just for what is a relatively simple site.

I pay for:

• the Cloud Run itself
• a LB in front of it
• the V4 address
• the V6 address
• the http -> https redirector for both v4 and v6
• the CDN

…yesh. It actually honestly works really well, but it just feels like a lot for a tiny blog. 🤯

Also, it connects directly to my GitHub repository and builds whenever I push. This is 👌: I previously had the incredibly awkward credential delegation stuff set up so GitHub could deploy on my behalf. (I do need to also trigger regular builds somehow in order to update 'the most popular' posts, but hopefully I make enough changes that I'll regularly see this update anyway.)

By the way, the swap to Cloud Run was largely spurred by App Engine's broken Custom Domains feature which added stupid amounts of latency. Honestly, this was embarassing: I used to work at Google literally on how to make your sites faster, and my own blog was incurring ~100-200ms+ wasted latency for some users.

Anyway, as far as I can tell, this is a failure of Google's internal teams to talk to each other (it's not run by Cloud, oh no) and a bit of legacy around what IPs it uses. So as usual, just use the new shiny because no-one at Google wants to fix, document or care about the broken feature.

Fly.io

I've been hacking with Fly.io lately. It's a really interesting inversion of the traditional big cloud model—you can set up Docker-like VMs which spin up very fast and can be trivially replicated worldwide. (This feels 'hard' to do on traditional cloud providers—Google only vaguely supports this IIRC on Firebase/Cloud Functions.)

Fly's model is that there is no "batteries included".

• If you want a database on Fly, you… just run a database.
• If you want an event queue, you… just run an event queue.
• If you want a CDN, you… get the idea.

This is not the fever dream of people who long for fully integrated PaaS, because you have to do a lot yourself. Ironically, one of the clearest use-cases for Fly is something like a fast static blog with low/minimal server part, because you can just blat it worldwide trivially, but your synchronization story becomes complex (or at least still singly-homed).

I even wrote a small library, Hangar, to help develop Fly apps locally, basically helping you emulate the distributed production environment.

Also, I have a longer post about building webapps using long-lived services like this coming soon. 👀

GitHub Pages Deploy

I'm now using GitHub to deploy content to GitHub pages for quick/lazy hosting for demos.

I think what's notable here is that I can now build a GitHub Action that deploys directly to GitHub Pages without having to awkwardly push to another branch and/or folder. At least previously, you had to choose a path to serve from, and it was always super weird to have your action commit its artifacts.

For example, I've deployed a hacky project svg-earth. Its build file is here, but you can basically follow the obvious path.

Amusingly, all the examples use frameworks but none just call npm build. Weird.

Vite

I've normalized a bit on using Vite for everything web.

In old times, I wrote dhost, which included cache-busting and module import rewrite support (just for .js). It still gets used a bit when I want to serve build artifacts, but its time is otherwise done.

Sort of related, Santa Tracker, even though I'm not involved anymore, went off without a hitch this year. The way I designed its build system is very Vite-like, and I think even possibly predates it: a local dev serving path that rewrites every file, but a more complex build step. I never productionized it for anyone else, though.

Cloud Libraries

I regularly find myself reusing code from prior projects. And honestly, managing individual packages is a pain. So I've started publishing 'super-packages' that contain things I need, but in a way that makes them reasonably tree-shakable.

thorish (JS/NPM)

I publish thorish for JS. This mostly contains primitives around concurrency (well, JS' concurrency…)—things like work queues that I find myself often recreating.

By the way, I like (although it seems broken/slow at times) the autogenerated docs tsdocs.dev as it's very Go-like and it also means I don't have to bother generating docs myself.

thorgo (Go)

And speaking of Go, I publish thorgo. I've started to work more with context.Context in Go, writing some helpers for that. I've realized that it's really paramount to JS' AbortController/AbortSignal, and it should be used far more often for close/shutdown mechanics for any type of helper—i.e., you only ever have a Join method, and shutdown is entirely based on the passed context.

My Queue type, for instance, allows multiple users to subscribe to a queue of events. There's no channels used here, avoiding oddities with consuming/draining.

Business Stack

After leaving the startup earlier this year, I set up a Pty Ltd in Australia for consulting and services work. I'm building some basic SaaS for developers that may or may not land well, but at least it's something that I want myself.

Wise

I am overwhelmingly impressed with Wise, which let me set up a business banking account with almost zero fuss (and only a one-time $22 payment), and immediately provided me with both a digital and physical (in the mail) debit card.

This is in contrast to traditional banks, which needed umpteen forms of ID brought in-person to an office. And then they still have the gall to charge me $10/mo for a debit card.

To be fair, I think Wise won't and doesn't pay any interest on cash held by the account, but I have reasonably small amounts.

Invoicing

I haven't really found a "simple invoice generator" yet. Yes, I'm aware there's a million out there behind a Google search. No, this isn't the SaaS I'm building—don't worry.

All I've done so far is created a basic template in Google Docs and have edited it every time I've sent a new invoice, before storing the final generated PDF in a Drive folder for posterity (and you know, tax).

Fin

That's all for now. Happy new year, watch this space, etc. 🎉

Baldur's Gate 3 Character Choice

My partner and I have been playing co-op Baldur's Gate 3 on PS5.

It's good, although a bit clunky on controller, and while the split-screen mode is amazing that it works at all, it's also the source of pretty hefty FPS drops. When cross-play is added, one of us will probably swap to a Mac to keep playing.

How Your Character Choice Works

We found character creation confusing, especially as you're sort of dumped into it… what does it mean to pick an "origin character"—a premade character with backstory—versus a character you build yourself.

If you choose an origin character, you play "as" them— they are your 'avatar'. This sounds reductive, but the differences are simple:

• There are absolutely no voiced lines from your character: you imagine yourself saying things as you choose dialogue options
• You get additional backstory in the form of extra choices, cutscenes during rest, etc.

(This choice is especially confusing because the character picker has a small cutscene where the characters 'pitch' you on choosing them in a fun little voiced story. These are enjoyable, and you'll pick a character you like, but then you'll be incredibly disappointed when you finally realize you won't get to hear them for the rest of the game). 🔇

If you collect origin characters during play, you see their stories from outside. It doesn't matter if you're another origin character or a self-made character.

• You'll get to interact with them, possibly with special lines as an origin character yourself
• They'll be fully voiced
• You won't get their extra cutscnes, but instead only hear about their experiences as they discuss with you.

(There's also a large number of PCs who you collect—like Halsin, the Druid—who come later, so you could never play "as" them. These aren't really origin characters, but act like ones that you could have never taken as your avatar.)

Finally, if you build your own character, you'll need to invent your own backstory. This is almost the most 'observational' way to play. You'll have some particular origin as defined by D&D—in my case, I think I'm a sage or something—and that will effect your rolls and experience. But there's no hidden backstory to your character that you'll uncover or learn more about during the game, you primarily experience the story as an outsider.

In-Game

Confusingly, even though you have a clear avatar, you can choose any character to 'lead' your party. This is incredibly versatile! You can split your party into multiple groups, have them in different parts of the map, etc. You can even initiate discussions with NPCs not as your avatar. Any dialogue lines at this point continue to be unvoiced, and the relationship implications of your dialogue still apply to your avatar.

For example, "Shadowheart approves" can occur even if Shadowheart (as a 'collected' party member) is the only one in dialogue.

Additionally, there are a number of global states that are applied party-wide. At one point we (in co-op) interacted with NPCs far apart on the map rapidly in sequence, and had differing conversations that included lines like… "we hear you've discussed this problem with «the other party»", which we'd done literally seconds ago.

A Note On Replayability

The origin characters make BG3 especially replayable because every one has hidden development that will only be exposed if you play as them. This is honestly very D&D-like, again, Baldur's Gate is literally D&D, but more in the sense of… here is some backstory that the DM only shares with you, even though clearly playing the game is more or less a shared co-op experience where you want to win together.

If you want my opinion on who to choose in single-player… I think it depends if you're the sort of person who might replay the game.

• If you're only going to play through once, I'd suggest choosing an origin character. The experience of extra hidden backstory is interesting enough.

• Otherwise, I'd suggest playing as a BYO character, and then you can find the most interesting origin characters to play as next time.

Of course, if you're playing co-op…

How Does This Interact With Co-Op

For Nicky and I, we're playing as Lae'zel and a BYO character. I think that's probably a good combination because we get to experience unique plot as one origin character while still having the full gamet of other collected characters to interact with.

We tend to then have one additional party member under our control, as you have to explicitly assign them in multiplayer—this effects how you move them on the map and who is playing as them during combat. I find the explicit control actually a bit odd, because there's already a clear "grouping" mechanic—but I digress.

If we'd chosen two origin characters (which is possible, if everyone playing joins at the start of the game) you end up in the slightly odd state where your two origin character avatars don't really interact—if everyone playing multiplayer has chosen an origin character, you basically just don't have dialogue together, romance options, etc.

For us, we can't interact between our BYO character and Lae'zel, but that's less impactful as the BYO character is already in that "outsider" role.

Notably the way this works has really hit people who want to play four-player on PC, because then your party (maximum size 4) is literally full of people who… just don't have anything to do with each other. Honestly, I wouldn't recommend BG3 multiplayer for more than two, because it's really fun to have voiced characters hanging around giving their opinions. At this point it already feels restrictive only having two slots for them—we're having to swap them in and out far more than I'd like.

Yes, all the origin characters hang around at camp and have opinions there, and I think it's even possible to finish parts of their side quests without them being actively in your party. But this is just a bit odd.

Fin

We're enjoying BG3 as co-op (on easy, ha) but I'd say we're still naïve at some of the mechanics. I certainly haven't really played D&D or anything similar since University times. Our actions tend to be using fire cantrips (always available spells) or just regular hand attacks. The game itself is interesting enough without really getting super complex with our characters, though, as most of our abilities are only impacting our effectiveness in combat.

(We would totally recommend having a character who can Speak with Animals and jump really far, though).

Opinions On Sydney Rail Transport

This is a post containing my niche opinions on Sydney's public transport system. If you're from Sydney and a transport nerd, this is probably interesting. Otherwise, maybe read something else.

I'm not going to give background, suffice to say that Sydney is Australia's biggest city and has the highest number of commuters who use public transport.

Without further ado, some spicy takes. 🌶️

Takes

Isolate the Eastern Suburbs line

Sydney has an interesting history in that all its rails are standard gauge, making the entire train network actually useful for interstate travel and freight. (This is unlike every other city with trains in Australia, which all have a largely isolated narrow or wide gauge network.) However, parts of the network are useless for this because they're so isolated.

Proposal: The Eastern Suburbs line from Redfern to Central should be "cut off" from the rest of the network.

It makes no sense that I can get on a train at 9:13 from Bondi Junction and end up in Kiama at 11:39. Kiama is no different than Gosford or Newcastle in this regard: it's an intercity location, so you can encourage tranfers.

Now, you could extend the line westward from west of either the existing Central or Redfern stop, with stops at places like RPA (woefully underserved right now for a major health district), Leichardt, and perhaps Ashfield for another interchange. This extension works because you can keep running the T4 line between Central and Bondi Junction while you do the construction; just splice in new tunnels to extend the already underground route west, and keep the portal to the rest of the system.

This doesn't need to be a metro in the "driverless" sense, but it's an acceptance that you don't need to run trains so far.

Don't Metro Everything

The last few months have seen a few takes that the Sydenham to Bankstown part of the metro conversion might happen later, or not at all. I tend to be fine with this, even though a lot of the work has gone into upgrading stations already.

Sydenham is just a great place to do an interchange^. You don't need to run trains so far if you can literally swap onto another train with a couple of minutes anyway, and it gives you more backup in the network. To me, while the T3 line is kind of this weird bastard child of Sydney's ancient rail network, it seems to serve as a relief to the main western corridor, and converting it to a metro prevents interesting use like this.

So yes, remove the T3 lines from the City Circle, of course. But just stop it at the three-pronged boundaries of Sydenham, Lidcombe, and Liverpool.

^except the track arrangement is a bit weird, because you only have the Metro lines then four other stations which need to be shared. Could you stop both the T4 line and the T3 lines here, forcing people onto Metro/T8 or something like shuttles around the City Circle?

Badgery's Creek Airport

Metros are sexy and the Liberals hated the unions, so build a driverless metro in the middle of no-where. Uhhh.... sure.

Yes, this line should just be built into the Sydney Trains network, and eventually "circle around" to Leppington.

This is probably the least likely thing to happen on this list though, because it's not even technically compatible with the rest of the network (25kW AC).

Picton

This technically isn't Sydney trains, and not even a spicy take, but just straighten the line south. It's a no-brainer and you have to start somewhere to reduce time to regions like Bowral, or even Goulburn or Canberra. The problem with all governments around these infrastructure projects is that they all think it should be huge, monumental, or have a giant business case. No! Just straighten some curves, and do a little bit every year.

Honestly, the same advice goes for the train north to Gosford and Newcastle, but the terrain makes it so much harder to do: we're relying on hand-cut tunnels from ~100 years ago, which are miraculous but probably hard to reproduce today (i.e., safety costs money).

Ring Light Rail

I watched a video a while ago on "ring rail", specifically "ring light rail". Sydney is okay at not just having a hub-and-spoke model (*cough* Melbourne *cough*) but not perfect. If you want to have a few CBDs and not just route everyone into or around the CBD, you need alternative transport routes.

For me, the most obvious place to put something like this is to connect the numerous western lines in Sydney, allowing for fast interchange between these 'corridors'. Honestly, it could be a metro instead, but light rail has the side effect of actively removing options to drive. (Yes, sorry.)

You'd connect these major locations:

• the new Metro West stop on Paramatta Road in Burwood
• down Burwood Road, directly connecting to Burwood Station
• to Campsie
• via Bexley or Kingsgrove
• to Rockdale or Kogarah
• optionally ending at Brighton-Le-Sands.

The biggest win here is honestly anything that connects to the Metro West stop, which is kind of weirdly placed on Paramatta Rd—folks aren't interchanging from their cars, so you need to make the station work with feeders from around the area. It just makes sense to extend south to Burwood, and then the other centers are a long way away, but again, the goal here is to reduce friction going into the city and back.

Ignore the Northern Beaches

Honestly, the Northern Beaches (like Bondi Beach) have shot themselves in the foot for decades. There's occasional thoughts of running train lines up to high NIMBY areas, but it's just not worth it: it's time to give up.

Less Spicy Takes

• High-density around train and light rail stations (of course)
• Fix the Dulwich Hill end of the L1 line so trams can run more than every ~10 minutes in peak
• Turnback for Airport Line trains after Wolli Creek, so you can run shuttle services
• Extend the L3 light rail to Maroubra and beyond (maybe even turning down to Maroubra Beach 🏖️): Anzac Parade was literally designed for it
• Extend the metro to Schofields, but no further: make the Richmond line more useful to more people (yes, even though it's suburban hell)

That's all

I'm funemployed and have time to think about these while juggling a new baby. So this has been an incredibly quick writeup.

I also admit that I am hippy who lives in Glebe in a detached house and owns a Tesla, so even though I'm pro-development, maybe that voids my opinion. So tell me how wrong I am on the birdsite.

Or if you're from the NSW Government, call me 🤙

AWS Amplify Is A Grift

Yes, this is a punchy headline, but if you'll join me on this journey, you'll see how. 👀

So, here's the context. For the past year or so, I was at a renewable energy startup. It was a great experience, but I recently resigned: I'm having another child, and I just don't need to work full-time—so I'm not going to. To be clear, this post is entirely my opinion: as of writing, I'm only employed by myself.

The startup heavily used Amplify—I inherited that decision—but one of my major initatives was removing as much of it as possible. This took hundreds of engineering hours away from actual work.

So, let me be as clear as possible, and you can quote me personally on this: "AWS Amplify is actively harmful", primarily because of its database choice.

Consider using just a normal database—personally for me that would be Firestore (Google-hosted) or MongoDB (basically self-hotsed), because I strongly prefer scalable NoSQL databases. But for most people, it's probably going to literally just be Postgres. You don't need more than Postgres.

How can a framework be actively harmful?

A core idea of cloud providers is that you can build your infra and not have to worry about scale. AWS Amplify makes promises that it will be:

Easy to start, easy to scale

But herein lies the grift: it's useless for anything except toy applications with trivial amounts of data. And these toy apps are conveniently easy to demo.

And data is the key here; there's a lot of AWS Amplify which is just fine and boring, like its user authentication libraries. The issue lies with GraphQL and the way it stores data.

The challenge, of course, is that you don't know that it's terrible going in: that's why I'm writing this post. The issue is that it it's built by the world's biggest cloud provider, who is completely happy to pay US$200k/yrs to DevRels to push this unusable bit of software—so you might think, sure, it's fine.

But it's not. 💥

The Boring Stuff

Let's get the boring stuff out of the way. By that, I mean the parts of AWS Amplify that are innocuous, indifferent, and are plainly things that are hard to mess up or be particularly amazing at.

• Cognito: Amplify sets up an auth stack. It's got its own problems (including poor SSO integration that actively leaks all configured integrations), but if all you want is basic email/password login, it's fine. I've heard on the grapevine that Amplify's client-side JS is actually the best way to interact with Cognito.

• Hosting: There's a YAML-based config language which sets up some basic CI/CD to deploy your website. It's fine.

• Analytics: It's broken. If the same user signs in on a large number of different browsers (you'd never do that while debugging, in multiple Incognito windows—never!) then you generate too many IDs for that user and events can no longer be logged.

• Some AI stuff: I haven't used this. It seems like it's just AWS wrapping up its more complex services with… exactly the same level of complexity, but now it has a 🌈 brand 🌈.

Again, this is fine. Any provider pitched at the same level—Firebase, Supabase, Azure probably has one—has this kind of "app-builder" stack.

Data, It's What Apps Crave

AWS Amplify allows you to specify GraphQL models that turn into database rows. To be fair, this is an annoying problem: let's say you're DIYing it, and writing a GraphQL server and database integration yourself.

• If you're using a traditional SQL database you'll have to write both the GraphQL schema and the table schema.
• If you're using NoSQL, you may have to massage your GraphQL types before storing them—since GraphQL's type system is needlessly restrictive.

However, the fundamental mistake that's made here is that AWS Amplify puts your data into DynamoDB, which is not a general-purpose database.

Amplify's approach in using DynamoDB is literally called out as something you should avoid by AWS, because it uses a single table per resource. Additionally, you cannot filter or sort by arbitrary columns—DynamoDB is a high-performance, low-level database, that doesn't let you do arbitrary queries. That's the point.

Yes, Amplify awkwardly describes the way you can create secondary indexes, but it's often not what you need (everything needs primary AND secondary keys, etc), and you can't index on any sort of ACLs.

So using it is literally an anti-pattern. And part of the problem is, once you're in production using a database—whatever database, not just DynamoDB—it's hard to get out.

But DynamoDB Scales?

But Sam, you say—DynamoDB is a fast, scalable database. Surely these tradeoffs are worth it?

Yes, in some cases. But you should only use it when a traditional database won't cut it (and if you think you know what that threshold is, go and double the number and come back to me), and you can confidently design your queries up-front.

Amplify, which is literally pitched at startups, isn't suitable because you're going to pivot. Your CEO is going to ask you for some weird data 'shape' that just isn't possible because Dynamo plainly cannot answer your arbitrary queries. Yes, no data is ever in a perfect table, but this makes it worse.

There is a flipside, which is that Dynamo is fairly fast at a "scan", which is a fancy term for "load every row and filter it at runtime". And yes, if you don't have much data—again, think of a number and add an order of magnitude to it—you can just do that, but then why are you using DynamoDB? Dynamo scales by sharding—your primary key space is divided ito partitions. But a partition is literally 10gb of data.

• If you're storing that much plain text data, good for you—maybe DynamoDB can help you!
• If you've only hit 10gb since you're putting large binary data into your database, you should rethink your choices.

So if your company doesn't have that much data (even 100gb might be a good target), but chooses to use Dynamo, your effective option to do arbitrary queries is just to… scan all the data.

So why are you using Dynamo, a hyper-performant and extremely limited database, again? 🤔

But DynamoDB Is Fast?

Ah, well, here's the real killer.

If you put access controls on your data, and say, a user wants to retrieve their "Foos"… AWS Amplify literally has to fetch matching data and then filter it down.

Let me say that again. If you have 1,000 users, and each privately owns one row of data, Amplify's default pagination of 100 items per fetch will take—in the worst case—O(users/100) pages to retrieve the user's item. For 1,000, that's 10 pages. For 100,000, that's 100 pages—100 round trips from your user's web browser back to the database.

The VTL, a language used by AppSync, which is Amplify's underlying provider, looks like the following (a tiny bit snipped for brevity). And note that the 'data source' items are in $ctx.result.items—that's the page we have to scan to see if a user can see their own data.

#set( $items = [] )
#foreach( $item in $ctx.result.items )
  ## [Start] Dynamic Group Authorization Checks **
  #set( $isLocalDynamicGroupAuthorized = false )
  ## Authorization rule: { allow: groups, groupsField: "groupsWithRead", groupClaim: "cognito:groups" } **
  #set( $allowedGroups = $util.defaultIfNull($item.groupsWithRead, []) )
  #set( $userGroups = $util.defaultIfNull($ctx.identity.claims.get("cognito:groups"), []) )
  #foreach( $userGroup in $userGroups )
    #if( $allowedGroups.contains($userGroup) )
      #set( $isLocalDynamicGroupAuthorized = true )
    #end
  #end
  ## [End] Dynamic Group Authorization Checks **

  #if( ($isLocalDynamicGroupAuthorized == true) )
    $util.qr($items.add($item))
  #end
#end
#set( $ctx.result.items = $items )

Yes. It's really that bad. Of course, Amazon's sample resolvers (not that you write VTL directly with AWS Amplify) don't include this—they have a single line saying, "oh, you'll just pass all the data back to the client".

What Else Is Wrong?

The above criticism, the run-time filtering of user data, is by far the most egregious failure of AWS Amplify. There's a number of other poor areas, too.

Firstly, GraphQL subscriptions are basically useless. There's a great blog post here which covers this far better than I can.

And Amplify's DataStore fails fundamentally because it relies on GraphQL subscriptions and Amplify's view on that. It doesn't support dynamic ACLs (which is technically listed in the docs but not at all clear), so you can only listen to public items, which is bizzare. And it falls into the traps above. There are so many issues about how it's unusable and how the people filing didn't realize until they were already knee-deep in Amplify's grift.

Additionally, the JS used by AWS Amplify allows for race conditions in listening to changes. What do you do when you want a list of "live" objects? You'd imagine something like:

• You request the complete list of objects
• You listen for changes to those objects

And that's what Amplify does, … but here's the kicker, in a diagram:

So you're going to risk losing changes. And for most users—sure, that's fine. What are the odds of something happening in that red area? But it's poor design.

I know there's a slightly tweaked approach that has revision numbers and so on, but it's not commonly understood.

I cannot stress how much Google's Firestore just solves the 'real-time' problem. Instead, for days and days, I've had to work around Amplify's limitations.

What Should AWS Do?

So, you say: Sam, you've complained a lot. But Amplify has some redeeming characteristics. How could you make it better?

If I was AWS, I would…

• provide Postgres or similar as a database choice: This allows a developer's database schemas to include fairly arbitrary indexes (because you're not limited by DynamoDB)
• incorporate ACLs into that database's indexes: ACL-ed queries are 'slow' because they take the dumbest approach
• rebuild subscriptions without GraphQL: Implement a log-based solution which lets users catch up on a single table they're interested in, but trade off "nested" queries (it's not GraphQL anymore)
• rethink whether GraphQL is actually fit for purpose: It's just not very good, aside from nested queries. That's a whole different post, though.

What Should You Do?

If you're already commited to AWS Amplify, then I'm sorry. The auth and non-database world—that's fine. I even enjoy or think that the JWT-based approach to auth is actually fairly good, and you can write alternative backends which use a user's claims to enforce ACLs.

I think the thing I'd do is… if you're somewhat "successfully" using Amplify right now, I believe that your model and data won't actually be that large—because it actually breaks down at big numbers. Therefore it is the right time to rethink.

Look at your queries which are particularly awkward—what does your app or company have the most of? Can that be refactored into its own system, potentially wrapping up a database that's more fit for purpose?

Remember too that most applications will have a notion of login, user, settings—fairly boring stuff. If that's in Amplify, fine. A lot of it is probably ID-based, which Dynamo actually does excel at—you're not listing every user to get to your own. So that can remain.

Thanks For Reading

This space isn't perfect, but I honestly believe Amplify has too many potholes to justify its use, and those are wrapped up in poor documentation that hides a lot of nuances that aren't obvious when you start and only hit you when you're actually trying to scale.

Best of luck. 😬

Find me on Bluesky. I'm also available for consulting.

An Addendum

Update, April 2023: This post ended up on the front page of HN. I'd like to call out some themes in the comments:

• AWS uses Dynamo as it has no other Serverless database offering: This is actually a fairly astute observation. Amplify is pitched as a serverless product, and I'm not sure what AWS has in the database space that doesn't "run all the time"—running Postgres or Mongo would cost you ¢/hour.

• You shouldn't be using Dynamo for your data model: Sure, that's why this post exists. As a developer using a new app builder platform, it's not clear where the minefields are, and AWS Amplify doesn't make it clear from the outset that it has these really hard limitations around ACLs, speed etc. AWS isn't going to come out and say "Our database is a bit shit, but the rest of Amplify is perfectly cromulent.".

• Postgres vs NoSQL: I don't see Firestore (NoSQL) or Postgres being that different. I like Firestore. I think it's the world's best general-purpose database. But Postgres is similar enough, I think it just comes down to personal preference. DynamoDB, on the other hand, … is not really either of those things to me. It's a lower-level construct that people often build real general-purpose databases with, but which is highly limited on its own. This is my thesis: Amplify is doing the tech space a misservice by using DynamoDB.

AbortController for expiry

My last post on AbortController continues to be my most read blog post, ever. This one probably won't do quite as well, but that's fine—it's a bit more niche, but it's definitely also an extension of that one.

Today, the problem I'll solve is:

• you have a token, key, or some object (e.g., some key to access a system)
• it's valid only for some time (e.g., an hour) - it has a lifetime
• you want to ensure users of that object don't overstay their welcome. 💥

Background

The idea of AbortController is to generate an AbortSignal you can pass in to some object or system to later shut it down. For example, you can have one signal for an entire request, but shut down all its dependent work with one single call to .abort().

This background might feel a bit needless, but it actually reminds you that the AbortController has a very close relationship to the idea of "context" as it pertains to RPCs, network requests and so on: whenever your service handles an external request, create a single AbortController, and pass its signal (aka "context") everywhere.

If you're familiar with Go, then it has a standard library version of this.

Anyway, read on. 👇

Approach

To remind you, we're here to manage the expiry of some complex object: something that itself has a lifetime.

So instead of starting with a context-like object, you can create a helper function that builds your thing and its lifetime—where its lifetime is described via an AbortSignal. Something like:

/**
 * Builds an expirable role. Creates a new lifetime in its AbortSignal.
 */
async function buildExpirableRole() {
  const { expiresAt, token } = await getRole();  // the hard work!

  const c = new AbortController();
  const expiresAfter = (+expiresAt - +new Date);  // gives back an expiry Date
  setTimeout(() => c.abort(), expiresAfter);

  return { result: token, signal: c.signal };
}

When I call this method, I now get a result and a signal pair. I can use this to determine how long the result is valid for: has the signal been aborted? If so, it's no longer valid. 🙅

Re-using existing lifetimes

I've just created an expirable object that returns a new AbortSignal. What if the object has a lesser lifetime than some outer context? Then, you can just pass in an existing AbortSignal and create effectively a derived one:

async function buildDerivedExpirableRole(signal) {
  const { expiresAt, token } = await getRole();
  const c = new AbortController();
  const expiresAfter = (+expiresAt - +new Date);
  setTimeout(() => c.abort(), expiresAfter);

  // NEW CODE HERE
  if (signal.aborted) {
    c.abort();
  }
  signal.addEventListener('abort', () => c.abort());
  // END NEW CODE

  return { result: token, signal: c.signal };
}

We literally make the inner signal's lifetime shorter by piggybacking on the outer one's aborted state. In doing so, you'll have to deal with the awkward nature of AbortSignal: if it's already aborted, you can't just add an event listener, because it's already fired. (I have a helper for this, since I do this so often.)

Memoizing This Approach

Okay, you've got a thing and its lifetime—a pair of state. You can call this, but now you've got to hold onto this pair forever.

Instead, you'll want to memoize this: create a function which will automatically fetch a new value whenever the previous' signal has aborted/expired.

This is pretty simple. If you have some type ExpirableResult<R>, that contains the result and a .signal property (in TypeScript), then you can create a helper which holds onto the Promise while it is valid.

I've swapped into TypeScript for this one, since the types help a lot:

export function memoizeExpirable<R>(
  fn: () => Promise<ExpirableResult<R>>,
): () => Promise<ExpirableResult<R>> {
  let activePromise: Promise<ExpirableResult<R>> | undefined;

  return () => {
    if (activePromise !== undefined) {
      return activePromise;  // return already active promiswe
    }

    // there's no valid result, fetch a new one
    activePromise = fn().then((ret) => {
      if (ret.signal.aborted) {
        // already aborted! clear result immediately
        activePromise = undefined;
      }
      ret.signal.addEventListener('abort', () => activePromise = undefined);
      return ret;
    });

    return activePromise;
  };
}

Okay, that's a bit of code, but it's all fairly required. Again, this has the awkward part of managing an already aborted vs. newly aborted AbortSignal.

To use, you might do something like:

const getExpirableRole = memoizeExpirable(buildExpirableRole);

Now, you can call getExpirableRole—it'll return a Promise—to always get a valid role. Amaze! 🎉

An interlude on lifetimes and context

The previous example just accepts a function which computes an outcome with an expiry, but it doesn't accept a previous signal that has its own lifetime.

This is interesting to think about because you basically have two lifetimes when writing any sort of application.

1. The lifetime of a user's request (e.g., a network handler on a backend, a RPC), or interaction (perhaps as the user undertakes a complex interaction)
2. The lifetime of the app as a whole.

You might also have a concept of a "session", although this is hazy on the web.

Often these interactions are inexorably linked. Cloud Functions, or Lambdas, tend to be created on-demand on a user's initial request—they don't run all the time, otherwise you're paying the cost for that even when your server isn't being used. Lambdas will then have a keep-alive time when they can handle further requests (although this may only be a single request, if your activity is low).

So if you're getting a credential or role… what is the right "context", ala, the global AbortSignal to use? If it's the lifetime—well, you might not have a signal at all, because modern backends are overwhelmingly designed "to die". So "to die" is basically when the server just shuts down in an uncontrolled manner.

(Something I learnt early-on in my technical career is that no-one is ever "neatly" shutting down a backend in a controlled way. You build a thing, it's designed to run for as long as it can or to handle as many requests as possible, and there's no such thing as 'normal' shutdown. 🧨)

Thanks

Thanks! That's all for today.

Practical Python Modules

I grew up writing a lot of Python, which I guess speaks to how old and unorganized it is. And since then, I've been primarily a JS developer—that ecosystem has its failings, but the rules around how things are imported inside "node_modules" are mostly well established, even despite its quirks.

For modules, though—Python is a mess. But I think there's some simple knowledge that you might be missing. 🤔

So, You're Building A Package

Just some package that has some behavior or functionality. It does whatever. It might have some dependencies. But you want to structure it in a sensible way. 💡

You Want Module Mode!

Unless you're writing a single script file, I assert that you almost always want to run your code as a module.

# where "path/to/module.py" exists
python -m path.to.module

If "path/to/module" is a folder, Python will look for "__main__.py" within that folder. If it's a file, it'll run it directly. In both cases, __name__ == "__main__": you can still use that old trick to determine whether you're the startup script.

Benefits

The benefit of this is you get an actually sane relative import system. You can, and should only, write imports like this:

from .foo import whatever

…to import whatever from the peer file "foo.py".

You can also write things like:

# import "./foo_folder/something.py"
from .foo_folder import something

# import "./foo_folder/another_folder/blah.py"
from .foo_folder.another_folder import blah

# import "./hello.py"
from . import hello

# import "../up.py" (caveat: more on this later)
from .. import up

And best of all, if you have a file called "types.py", you don't have to literally worry about importing Python's built-in "types" module—you import it as .types.

Gotcha: Directory Layout / Working Directory

To run module code, it must be within a subdirectory of your current working directory.

Here's an example. This, unfortunately, works:

touch test1.py
python -m test1

But it quickly fails if we try to import something:

echo "from . import test1" > test2.py
python -m test2
# ImportError: attempted relative import with no known parent package

If you were to go up literally one directory, e.g.:

cd ../
python -m pythonsucks.test2

…this will import and run fine.

In a similar way, you can't escape the top-level package. I can't import ..foo if I'm within one of either "test1.py" or "test2.py", because there's only one directory above them in our module path.

This means that Python packages are gated to the current working directory of your Python interpreter. This restriction is absolutely bonkers (especially coming from a JS background), but once you know it, you'll appreciate what you can and cannot do.

Fun fact: You can run any Python file on your computer in a sane way by going to "/".

cd /
python -m Users.Sam.Desktop.pythonsucks.test2

This doesn't work if your folders have "-" or other weird characters in them, but it works.

Gotcha: Import Syntax Restrictions

You can't import a relative file like this—Python's syntax doesn't allow it:

import .hello  # <-- this does NOT work, so...

You instead have to do one of two options:

# For side-effects only - imports just a single symbol
from .hello import __name__ as _ 

# Import from self directory
from . import hello

The latter option works fairly well, and can be extended to e.g., the parent folder or subfolders:

from .. import peer_of_my_folder
from .subfolder import something_in_subfolder

Caveat: Can't Run File

In the examples above, even though the folder name is "pythonsucks", I'm not running Python by calling "python -m pythonsucks/test2.py". In fact, Python gives us an extremely unhelpful error message:

python -m pythonsucks/test2.py
# ImportError: attempted relative import with no known parent package

So whenever you run a file, you need to (a) replace "/" with "." and remove the ".py" suffix, and (b) make sure you're in a parent directory (as I said above, parent relative imports may fail unless you're above all of your Python code).

Notably this is an absolute pain in the ass when you're doing development work:

• Your shell probably isn't going to autocomplete module names
• You have to "cd" up to a parent folder whenever you want to test a file

It also means that you should effectively never put a ".py" file in the top-level of e.g., your git repository—it has no way of being executed in any sane way.

This is all a pain in the ass…but at least, now you know. Sigh. 😩

What About Requirements?

You might have some dependencies you can install. Python's dependency management systems are bonkers, too—that's a different post. (I have recently learned about pipenv, which is inspired by sane package managers—it may work for you.)

No matter how you install them, though, you should always import them with a name that does not include any leading dots.

Conversely, you should always import your own local code with a leading dot. (Sorry, I put a lot of emphasis in that sentence, but it's the rule.)

What about virtualenv?

I'm sorry. This post doesn't yet cover how this all interacts with that, but I suspect the answer is not much—the same module problems exist there, it's just that it's a way to include specific requirements/dependencies.

So you might be able to use the learnings here.

That's it.

Modern Python is nuts. I've spent hours pulling my hair out on this. 🫠

What I honestly want is a helper that lets me say:

python-module file.py

This helper would:

1. Walk my directory tree and find some "module root" marker (maybe this is the ".git" folder, or even "/")
2. Run "file.py" in the "path.to.file" syntax, treating it as a module

Phew. 😡

Hit me up on Twitter for any comments.

Focus Management in 2022 📺

I recently gave a talk! It's on <dialog> and the inert attribute, with a mention of <fieldset disabled>, too.

You can find the talk on JSNation, who graciously hosted me and motivated me to get this done. 🎉

But also, it's just on YouTube here (albeit without my face and a snazzy intro/outro):

This talk combines one of my quite popular blogposts—In Defence Of Dialog, including some great demos—with a bunch more new content about the other focus primitives you have available to you.

Inert Release / Fieldset Disabled

Everything I mentioned in my talk can work today, except…

As of July 2022, Firefox still hasn't shipped the inert attribute. This is something that I called out in my talk. It's completely implemented, but for some reason, Firefox won't throw it over the wall. This is amazing considering even Safari has come to the table.

I'll update this section when or if they do. But if you want some basic workarounds, consider <fieldset disabled> for forms. If you have a HTML form, you can make every <input>, <button> etc contained within disabled all-at-once:

<fieldset disabled>
  <button>I'm disabled because the fieldset is disabled!</button>
</fieldset>

<!-- This "wins" over the lower fieldset,
     so you can wrap complex forms in it -->
<fieldset disabled>
  <div>
    <span>
      <div>
        <main>
          <!-- If the parent is disabled,
               this one is disabled too -->
          <fieldset id="another_one">

<input type="text" value="I'm disabled too, because fieldset[disabled] propogates down" />

          </fieldset>
        </main>
      </div>
    </span>
  </div>
</fieldset>

Try a demo, too:

Note that <fieldset> has some default CSS (you can see it in the demo) that gives it some spacing and a default border. You can reset it by doing this:

fieldset {
  border: 0;
  margin: 0;
  padding: 0;
}

Or even better, you can do this so it has no representation whatsoever:

fieldset {
  display: contents;
}

Again, this won't disable things like <a href="...">, but will disable any HTML form element. Which may be good enough. 🤷

Thanks

Check out the video! Even on 2x. I promise it's interesting, and can give you far more power when writing complex web experiences—especially useful for folks interested in low-level primitives.

👋

Event-Driven JavaScript Development

Every JS developer has written code to handle "click" listeners—press a button, tap a link—and you'll do something interesting. Events are core to the way we write for the web and use the DOM. 👆

But what if I were to tell you that you should and could be using event-driven development for yourself—not even in the DOM? 🤔

To do that, we can now subclass EventTarget, giving your code access to fire its own events, and listen to those events using .addEventListener. This lets you properly encapsulate behavior—your abstraction can do some work, and other parts of your code can simply listen to when it's done.

Here's a simplified version of the demo's code:

class SomethingController extends EventTarget {
  async doSomething() {
    await someLongTask();
    this.dispatchEvent(new Event('amazing'));
  }
}
// now:
const c = new SomethingController();
c.addEventListener('amazing', () => ...);

Great! 🎉

Of course, I could have created the cute effect any way I liked—I didn't need events. But technically, the progress bar / button is totally separate from the effect—it's only connected with an event.

Hopefully the tl;dr code snippet is useful enough. But read on to find out:

1. Why this is better than .on or your own DIY event system
2. When to dispatch an Event, a CustomEvent or a subclass of either
3. How to make tell TypeScript about your new events, e.g., allow you to autocomplete in VSCode and have type-safety in the compiler
4. How to use a general-purpose object, which emits events, with {P}react

First, though! A bit of background. 🏔️

Background On Events

Elements on the page can emit events, such as a "click" event I mentioned above.

Depending on how the event is dispatched by the browser, it might be cancelable, and it may bubble/capture in interesting ways. This is just an accepted standard. For example:

• "click" events will typically bubble and be cancelable (because they're often on <a href> or some other interactive element, and you might want to disable that behavior)
• whereas "change" isn't cancelable, becuase it reflects a change on an <input> that's already happened

I think that the average web developer has a vague sense of these rules: e.g., when you click something, it'll generate an event which bubbles and fires at all places "up" the chain (finishing on document.body). ⛓️

However! This post is about subclassing EventTarget directly, and wrapping up behavior outside of the DOM. So things like bubbling have no analogy here: a pure EventTarget isn't in the DOM, so that property is irrelevant.

And subclassing already happens in some web APIs you might be used to! These include, but are not limited to, WebSocket, the legacy XMLHttpRequest, and the objects in the Web Audio API—these all have events, but aren't physically on the page itself. ❌📃

In Detail

Why this way?

An obvious question is—why do events this way? If you've been around the block, including in Node.js, you'll probably be well-versed in APIs that provide methods like .on('foo', () => ...), or .addListener(() => ...—really, whatever custom way to add events.

Yes, it's a little verbose, but compatibility / standardization is really the crux of it. The EventTarget and addEventListener combination is standard and built-in, so your users know exactly how they'll work and what they'll get—it's like any other object which emits events.

class MyObject extends EventTarget {
  constructor() {
    doSetupWork().then(() => this.dispatchEvent(new Event('ready')));
  }
}
const myObject = new MyObject();

myObject.addEventListener('ready', () => {
  ...
});

Also, you can use AbortSignal to make your use of .addEventListener more streamlined! Check out AbortController is your friend.

What type of Event to dispatch

To fire an event, you have to create an instance of Event. In the example at the top of the page, I've written a line like:

const e = new Event('something_done');
this.dispatchEvent(e);

And this is absolutely fine if your event is just a name with no attached data. Great! 👍

But if you want to attach some data to the event, you'll need to take a different approach. We have two ways to add something here. The first is to use CustomEvent, which allows you to add anything on its .detail property:

const detail = 123;  // literally anything can go here
const e = new CustomEvent('something_done', { detail });
this.dispatchEvent(e);

// later
foo.addEventListener('something_done', (e) => {
  console.info(e.detail);  // "123"
});

The second is to subclass Event and define your own properties:

class SomethingDoneEvent extends Event {
  constructor(value) {
    super('something_done');
    this.value = value;
  }
}

// use like this
this.dispatchEvent(new SomethingDoneEvent(123));

// later
foo.addEventListener('something_done', (e) => {
  console.info(e.value);  // "123"
});

So, what should you do?

• If an event doesn't need extra data, keep using Event with a custom name—this is totally fine
• But if you need to pass data around, I'd suggest subclassing: it's a bit more up-front work, but it's easier to understand the shape of the event: you're not awkwardly trying to remember what detail is supposed to be (although read on—types can help too) 😕

And, while it's definitely advanced, imagine a subclass of Event that has some additional functionality baked-in: maybe it acts like a stream between dispatcher and listener, or lets you call some function on it at a later point in time. While we're sending it around as an Event, it's still just a regular class.

And again, this is all possible with an arbitrary .details object, but gets awkward real fast. 🙅

Type Safety

When we use VSCode to interact with subclasses of EventTarget, we want to be able to type and see our options just appear. You probably also want typesafety if you compile with tsc, but honestly, the biggest win for me is VSCode not giving me a red squiggly line or having to cast to any. 😊

This doesn't happen for free just because WebSocket dispatches events. If you create a new object, like SomethingController, we have to actually tell TypeScript about the events it might dispatch.

But… this space is a mess. If we look at WebSocket in the TypeScript source code, it's ugly: 🤢

// NOTE: You don't have to do this! Keep reading!

interface WebSocket extends EventTarget {
  addEventListener<K extends keyof WebSocketEventMap>(type: K, listener: (this: WebSocket, ev: WebSocketEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
  removeEventListener<K extends keyof WebSocketEventMap>(type: K, listener: (this: WebSocket, ev: WebSocketEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
  removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
}

interface WebSocketEventMap {
  "close": CloseEvent;
  "error": Event;
  "message": MessageEvent;
  "open": Event;
}

TypeScript struggles with this kind of inheritance. So, the solution used in standard library is to include this incredibly verbose block every time, which has to itself know about events that could have been fired on the "parent", too. Not fun.

However! I'm here to make it easy. 🧑🏻‍🎤

Solution

I've built a type that provides a way to extend EventTarget (or things that already extend it, like HTMLElement or WebSocket, but that's not really the point of this post) with arbitrary new events, making them all typesafe. You can use it like this:

import type { AddEvents } from 'typed-event-types';

interface ObjectEventMap {
  "whatever": WhateverEvent;
  "ready": Event;
}

class ObjectThatHasEvents extends (
  EventTarget as AddEvents<typeof EventTarget, ObjectEventMap>
) {
  // your class code goes here
}

const o = new ObjectThatHasEvents();
o.addEventListener('whatever', (e) => {
  // hooray! This will autocomplete and `e` will be of type `WhateverEvent`.
});

It's a little verbose (and I'd happily accept PRs to make it better). But it's definitely nicer than having to manually plumb in new addEventListener calls.

Go use it in your projects. And note! This is just adding types—there's no runtime cost to this—we're just hinting to TypeScript that these events exist.

Use EventTarget with {P}react Hooks

If you're a developer who only operates in {P}react-land, you might be saying: this is great, but how do I cause a hook or render to 'trigger'? Can I still use {P}react idioms here?

Well, the answer is—you can, and you can't. Once you're writing classes to wrap up functionality, you are well out of {P}react-land. But that can be a useful construct as now you're not trying to "fit" into a framework's box.

But effecting state? That's definitely possible, although has a bit of boilerplate. Let's say our SomethingController changes some value on itself, and fires the "whatever" event when that happens. You can provide a hook like this:

const useSomethingValue = (c: SomethingController) => {
  const [value, setValue] = useState(() => c.value);

  useEffect(() => {
    const handler = () => setValue(c.value);
    c.addEventListener('whatever', handler);
    return () => c.removeEventListener('whatever', handler);
  }, [c]);

  return value;
};

And now your users can interface with SomethingController, and have a hook that provides a value that's always up-to-date. 🗓️

An Extension On Events

There's some other interesting facts about events that didn't fit elsewhere.

• When an event is dispatched by a browser, it's a single object. Naïvely, you might assume the object is cloned and sent anew—sadly, no.

So, if you have several "foo" listeners triggered by a user action, they'll each recieve the same instance of the event you passed to .dispatchEvent(...). This is not overly important except if you start passing data around, either with the CustomEvent instance, or your custom subclass—if your handler mucks with it, another listener will see the change. (But who knows—maybe this is a feature to you, not a bug. 🪲)

• Events are delivered synchronously. This is actually largely unlike event loops in many native platforms.

When you call .dispatchEvent(...), all registered listeners are invoked before the next line of your code runs. In fact, if any event listener throws an exception, that'll stop execution of all others.

I have two thoughts on this. I actually think that this behavior is fine, but I think that events that occur after long-running tasks can be nicely wrapped up in a microtask. This looks something like:

class Foo extends EventTarget {
  async longTask() {
    await longThing();
    queueMicrotask(() => {
      this.dispatchEvent(new Event('long_task_done'));
    });
    // maybe something else happens here
  }
}

In this way, your Foo won't experience a crash itself—it'll just show up as a global error.

This is somewhat controversial—lots of documentation says that window.onerror (in your browser) and "uncaughtException" (in Node) are definitely only meant as last-resorts, and you shouldn't be actively trying to trigger them.

But your event listeners that crash on when triggered from native code, e.g., event handlers for WebSocket or any DOM element- well, they already cause this kind of error.

So of course, you should attempt to write event handlers in a way that avoids crashes. (If you're really worried, try wrapping the body of your handler in a try/catch block.)

• Events handlers can be async. They technically shouldn't be—they're called synchronously, so… hear me out.

Perhaps counter-intuitively, my point above absolves your sins in writing async event handlers. I say this a bit facetiously. I've previously criticized event handlers that are async: "it's not async, events are fired synchronously, please fix that code". 😤

But! Event handlers can crash in uncontrollable ways anyway. You can't control this. So making them async is not any more dangerous. They might still crash! Just… later. 🤣

The most important take-away from async event handlers to remember that your async event handler will not block other handlers. For example, this code:

class Foo extends EventTarget {
  testEvent() {
    console.info('before');
    this.dispatchEvent(new Event('testEvent'));
    console.info('after');
  }
}

const f = new Foo();

f.addEventListener('testEvent', async () => {
  console.info('async handler immediate');
  await new Promise(resolve => setTimeout(resolve, 0));
  // this will happen after everything else is done:
  // it doesn't block "testEvent" from completing
  console.info('async handler after');
});

f.addEventListener('testEvent', () => {
  console.info('non-async handler');
});

f.testEvent();

…will output:

before
async handler immediate
non-async handler
after
async handler after

Phew. Rant over!

Why Event-Driven JS?

Well… these objects look fine, but maybe you're still asking why writing a controller, or object, helps you at all. 🤔

Using events falls into a category of—there are lots of traditional software engineering patterns that I think on the web tend to be forgotten in favor of trying to fit awkwardly into a framework's box. By looking at how the platform itself provides abstractions, like WebSocket, and building them ourselves, we can build better software—you should be hiding complex behavior inside primitive classes.

Personally though?

I am a somewhat senior generalist software engineer. Yes, I write about the web, my role is the CTO of an energy SaaS that has a single, large React app. But software engineering, more than a specific technology, is about building complex systems and making them work together.

And how do you do that? With good abstractions. 💡

What that means is—if you find yourself trying to mix two different types of state, or hitting the limit in your current development "context", whether that's a… {P}react component, callback, whatever, maybe you should consider pulling out the thing you're trying to do into its own object.

And then, what this blog post is all about, use events as one of the many ways you can interact with that object. As well as, potentially, writing a TypeScript interface for that object, so that the how is separated out from the what.

As an extension—this post isn't about interfaces, after all—the standard answer to why you need an interface is that you have many classes doing the same thing. That's not actually the best reason for them, in my opinion.

For me, an interface or any abstraction forces you to separate out concerns—this lets you think of put some functionality away in a nice box 📦, and compartmentalize it. Your team, or even your future self, will thank you! That complex functionality is now hidden behind just a few, clear methods, rather than leaking all over the rest of your code. 🫠

Done

This has been a long post. Like everything I write, I hope it's been useful! 😬

For me, researching the TypeScript definitions and finding a solution to the 'generic events' problem has been invaluable, and I hope you'll consider depending on the "typed-event-types" package—again, it's purely types, so has no impact on your build size—to embrace event-driven JS.

See you next time! Follow me on Twitter. 🐦

Cross-Tab Title Hints

Let's say you've built a website that shows items—maybe things you can buy online, or a catalogue of TV episodes. Your users are opening lots of tabs at once 📈 to compare and contrast, or decide what to buy, or whatever.

Turns out, we can use just the hidden tabs as a surface to help the user out. But note that this is really a desktop-only feature, because tabs aren't really visible on mobile. 📱

So first! Play with the demo:

And check out the video if you'd like to hear about it in <2 minutes:

The very short version of this is: if your users are trying to compare and contrast items, you can give your users visual cues by taking over hidden tabs' titles (and favicons, but that's an exercise for the reader) and showing them relevant information–without having to switch tabs.

To put it differently:

Build It

Let's talk about what makes this work and how to build it!

Broadcast Channel

First, let's learn about the humble BroadcastChannel. This is a tool which lets all pages and workers on the same domain broadcast messages to another. You can actually test it entirely on one page, although that's not really powerful on its own:

const b1 = new BroadcastChannel('some-topic-name');
const b2 = new BroadcastChannel('some-topic-name');

b2.onmessage = ({ data }) => console.info('got data', data);

// will go to b2 and other matching channels
b1.postMessage('hi');

The power 🔌 comes in that any other page that creates the same topic'ed BroadcastChannel will recieve the message too. Neat!

This is pretty much as basic as it gets. It's not enormously different than posting directly to a Worker or another window, except that it doesn't support transferable objects—there's not a 1:1 mapping to the target, so it's not clear who would own it. 📝

Focus Management

This blog post is a bit of a 2-for-1: focus management is wholly unrelated to 🔊 broadcast, but here we are.

The problem: you want to do something while an element is focused, and stop when it's not. I think naïvely people think, okay, let's create one "focus" and one "blur" handler and try to maintain state. But you can honestly get yourself into knots. 🪢

It's simpler to instead, set up one handler which itself adds a cleanup task:

thing.addEventListener('focus', () => {
  doStart();

  thing.addEventListener('blur', () => {
    doStop();
  }, { once: true });  // important!
});

This works because the browser basically guarantees event order—we'll always see an element focus and blur before any others do. This also works when a tab is wholly unfocused—your browser only has one tab and one element active at once 1️⃣, not one tab per page. ❌📃📃📃

Putting It Together

Now that we can track focus, and broadcast, we can request that other tabs make noise. Start with HTML like:

<table>
  <tr tabindex="0" id="tableRow">
    <th>Rating</th>
    <td>⭐⭐⭐</td>
  </tr>
</table>

And JS to match:

const channel = new BroadcastChannel('displayInfo');

tableRow.addEventListener('focus', () => {
  channel.postMessage({ action: 'start', prop: 'rating' });

  tableRow.addEventListener('blur', () => {
    channel.postMessage({ action: 'stop' });
  }, { once: true });
});

Great! …except, we now need to listen to requests and update our title accordingly:

const originalTitle = document.title;

channel.onmessage = ({ data }) => {
  if (data.action === 'start') {
    document.title = getMyRating() + '-' + originalTitle;
  } else {
    document.title = originalTitle;
  }
};

function getMyRating() {
  // TODO: something like:
  return tableRow.querySelector('td').textContent;
}

And that's it, albeit a fairly simplified version. Easy visibility for your users to compare and contrast information. 📊

Done

Thanks for reading!

There are some caveats to this demo. First and foremost, as I mentioned above, this doesn't really help you on mobile, because tab titles are rarely (if at all) visible.

Secondly, and this is a big one, browsers may totally reserve the right to stop you being annoying.

And this feature does drift dangerously close to that: imagine a tab that, when opened, constantly changed its title to say "HEY LOOK AT ME". My hunch is that if you're above a certain engagement threshold—and this is a concept inside Chrome and others, which you can find at chrome://site-engagement/—it'll be allowed, and not otherwise. That's probably fine.

This was largely inspired by a tweet I can't find any more, where someone claimed that IKEA was doing this for furniture sizes. Actually, this was a cute feature of Safari—it was getting rid of a common title prefix. But I think it's cute to do yourself, and the interactivity lets us extend on it just a little bit. 🆒

Follow me on Twitter for more like this. 🐦

AbortController is your friend

One of my favorite new features of JS is the humble AbortController, and its AbortSignal. It enables some new development patterns, which I'll cover below, but first: the canonical demo.

It's to use AbortController to provide a fetch() you can abort early:

And here's a simplified version of the demo's code:

fetchButton.onclick = async () => {
  const controller = new AbortController();

  // wire up abort button
  abortButton.onclick = () => controller.abort();

  try {
    const r = await fetch('/json', { signal: controller.signal });
    const json = await r.json();
    // TODO: do something 🤷
  } catch (e) {
    const isUserAbort = (e.name === 'AbortError');
    // TODO: show err 🧨
    // this will be a DOMException named AbortError if aborted 🎉
  }
};

This example is important because it shows something that wasn't possible before AbortController came along: that is, aggressively cancelling a network request. The browser will stop fetching early, potentially saving the user's network bandwidth. It doesn't have to be user-initiated, either: imagine you might Promise.race() two different network requests, and cancel the one that lost. 🚙🚗💨

Great! And while this is cool, AbortController and the signal it generates actually enable a number of new patterns, which I'll cover here. Read on. 👀

Prelude: Controller vs Signal

I've demonstrated constructing an AbortController. It provides an attached subordinate signal, known as AbortSignal:

const controller = new AbortController();
const { signal } = controller;

Why are there two different classes here? Well, they serve different purposes.

• The controller lets the holder abort its attached signal via controller.abort().

• The signal can't be aborted directly, but you can pass it to calls like fetch(), or listen to its aborted state directly.

  You can check its state with signal.aborted, or add an event listener for the "abort" event. (fetch() is doing this internally—this is just if your code needs to listen to it.)

Put differently, the thing being aborted shouldn't be able to abort itself, hence why it only gets the AbortSignal.

Use-Cases

Abort legacy objects

Some older parts of our DOM APIs don't actually support AbortSignal. One example is the humble WebSocket, which only has a .close() method you can call when done. You might allow it to be aborted like this:

function abortableSocket(url, signal) {
  const w = new WebSocket(url);

  if (signal.aborted) {
    w.close();  // already aborted, fail immediately
  }
  signal.addEventListener('abort', () => w.close());

  return w;
}

This is pretty simple, but has a big caveat: note that AbortSignal doesn't fire its "abort" even if it's already aborted, so we actually have to check whether it's already finished, and .close() immediately in that case.

As an aside, it is a bit bizzare to create a working WebSocket here and immediately cancel it, but to do otherwise might break the contract with our caller, which expects to be returned a WebSocket, just with the knowledge that it might be aborted at some point. Immediately is a valid "some point", so that seems fine to me! 🤣

Removing Event Handlers

One particularly annoying part of learning JS and the DOM is the realization that event handlers and function references don't work this way:

window.addEventListener('resize', () => doSomething());

// later (DON'T DO THIS)
window.removeEventListener('resize', () => doSomething());

…the two callbacks are different objects, so the DOM, in its infinite wisdom—just fails to remove the callback silently, without an error. 🤦 (I actually think this is totally reasonable, but it is something that can trip up absolute novice developers.)

The net effect of this is that a lot of code that deals with event handlers just has to keep hold of the original reference, which can be a pain.

You can see where I'm going with this.

With AbortSignal, you can simply get the signal to remove it for you:

const controller = new AbortController();
const { signal } = controller;

window.addEventListener('resize', () => doSomething(), { signal });

// later
controller.abort();

Just like that, you've simplified event handler management!

⚠️ This doesn't work (and will fail silently) on some older Chrome versions, and Safari before 15, but this will go away as time moves on. You can check (and add a polyfill) using my code here.

Constructor pattern

If you're encapsulating some complex behavior in JavaScript, it can be non-obvious how to manage its lifecycle. This matters for code which has a clear start and end point—let's say your code does a regular network fetch, or renders something to the screen, or even uses something like WebSocket—all things that you want to start, do for a while, then stop. ✅➡️🛑

Traditionally you might write code like this:

const someObject = new SomeObject();
someObject.start();

// later
someObject.stop();

This is fine, but we can make it more ergonomic by accepting an AbortSignal:

const controller = new AbortController();
const { signal } = controller;

const someObject = new SomeObject(signal);

// later
controller.abort();

Why do you want to do this?

1. This limits the SomeObject to only transition from start → stopped—never back to started again. This is opinionated, but I actually believe it simplifies building these kinds of objects—it's clear they're single-use, and are just done when the signal is aborted. If you want another SomeObject, construct it again.

2. You can pass a shared AbortSignal from somewhere else, and aborting SomeObject doesn't require you to hold SomeObject—a good example here is, let's say several bits of functionality are tied to a start/stop cycle, that stop button can just call the effectively global controller.abort() when it's done.

3. If SomeObject does built-in operations like fetch(), you can simply pass down the AbortSignal even further! Everything it does can be externally stopped, and this is a way to ensure its world is being torn down properly.

Here's how you might use it:

export class SomeObject {
  constructor(signal) {
    this.signal = signal;

    // do e.g., an initial fetch
    const p = fetch('/json', { signal });
  }

  doComplexOperation() {
    if (this.signal.aborted) {
      // prevent misuse - don't do something complex after abort
      throw new Error(`thing stopped`);
    }
    for (let i = 0; i < 1_000_000; ++i) {
      // do complex thing a lot 🧠
    }
  }
}

This is showing off two ways to use the signal: one is to pass it to built-in methods which further accept it (case 3. above), and just checking whether calls are allowed (case 1. above) before doing something expensive.

Async work in (P)react hooks

Despite some recent controversy about what exactly you should do inside useEffect, it's pretty clear that a lot of people do use it for fetching from the network. And that's fine, but the typical pattern seems to be to make the callback do async work.

And this is basically gambling. 🎲

Why? Well, because if your effect doesn't finish before it's fired again, you don't find that out—the effect just runs in parallel. Something like this:

function FooComponent({ something }) {
  useEffect(async () => {
    const j = await fetch(url + something);
    // do something with J
  }, [something]);

return <>...<>;
}

What you should do instead, is create a controller that you abort whenever the next useEffect call runs:

function FooComponent({ something }) {
  useEffect(() => {
    const controller = new AbortController();
    const { signal } = controller;

    const p = (async () => {
      // !!! actual work goes here
      const j = await fetch(url + something, { signal });
      // do something with J
    })();

    return () => controller.abort();
  }, [something]);

  return <>...<>;
}

Now that's a very simplified version that requires you to wrap your calls. You might want to consider writing your own hook (e.g., useEffectAsync), or using a library to help you.

However, remember that in hook-land, the lifecycle of what you have access to after your first await call is really unclear—your code technically references the previous run. Things like setting state tend to be fine, but getting state is not going to work:

function AsyncDemoComponent() {
  const [value, setValue] = useState(0);

  useEffectAsync(async (signal) => {
    await new Promise((r) => setTimeout(r, 1000));

    // What is "value" here?
    // It's always going to be 0, the initial value, even if the button
    // below was pressed.
  }, []);

  return <button onClick={() => setValue((v) => v + 1)}>Increment</button>
}

Anyway, that's a whole other post on React lifecycle gotchas.

Helpers that may or may not exist

There's a few helpers which may or may not be available by the time you read this post. I've mostly demoed very simple use of AbortController, including aborting it yourself.

• AbortSignal.timeout(ms): This creates a solo AbortSignal which will be automatically aborted after a given timeout. This is easy to create yourself if you need to:

function abortTimeout(ms) {
  const controller = new AbortController();
  setTimeout(() => controller.abort(), ms);
  return controller.signal;
}

• AbortSignal.any(signals): This creates a signal which is aborted if any of the passed signals are aborted. Again, you can construct this youself—but watch out, if you pass no signals, the derived signal will never abort:

function abortAny(signals) {
  const controller = new AbortController();
  signals.forEach((signal) => {
    if (signal.aborted) {
      controller.abort();
    } else {
      signal.addEventListener('abort', () => controller.abort());
    }
  });
  return controller.signal;
}

• AbortSignal.throwIfAborted(): This is a helper on AbortSignal which throws an error if aborted—preventing you from constantly checking it. You use it like:

  if (signal.aborted) {
    throw new Error(...);
  }
  // becomes
  signal.throwIfAborted();

This is harder to polyfill, but you could write a helper like:

function throwIfSignalAborted(signal) {
  if (signal.aborted) {
    throw new Error(...);
  }
}

All done

That's it! I hope that has been an interesting summary on AbortController and AbortSignal.

Follow me on Twitter for more sass. 🐦

Unit Testing React without Jest

Jest is clearly a polished testing tool, but with the advent of Node.js 18, we really don't need it any more. Jest also has a huge surface area, is perhaps inexorably linked to Webpack, and needs its own binary—you can't just "run the tests" as a script. So it has some modern challenges.

This blog post will teach you how to set up your code, rather than provide an all-in-one solution, and is not about React testing itself—just the environment where you can do it. We'll still be using the @testing-library/react dependency, and esbuild to do our build.

As it's just a set up guide, you might still want to write a small wrapper or use a library. But by the time you've finished reading, you should have a better sense of what's going on—unit testing isn't magic ✨, but it is important.

The Steps

Let's get right into it. 🤠

0. Build with esbuild

This guide assumes you're building with esbuild, but you could swap this out for another build tool. You should be able to build your React code already to a regular JS file, with a command something like this:

$ esbuild index.tsx --bundle --format=esm --outfile=dist.js

1. Write a test

Well, you'll need a test. Here's a simple one and the component that's under test:

const FooComponent = ({ text }: { text: string }) => {
  return <div>Hello <span data-testid="hold">{text}</span></div>;
};

test('test component', () => {
  const result = render(
    <FooComponent name={Sam} />,
  );
  // Check that FooComponent renders my name properly.
  const span = result.getByTestId('hold');
  assert.strictEqual(span.textContent, 'Sam');
});

It says hello to someone, and we'll just check that the contents of the element are correct. Sure, it's just for a demo.

So if we add the right imports, and build/run our test, …the test won't run, since we're using a lot of globals that don't exist—render, test, and assert. Let's keep going 👇

2. Add the right imports

Since we're no longer using Jest, we need a couple of important imports—there aren't just magic globals available anymore. Let's add these:

// You may want to / need to import React, depending on build setup
import React from 'react';

// Node's built-in testing libraries
import test from 'node:test';
import assert from 'node:assert';

// We still want a helper, and this is a great one
import { render } from '@testing-library/react';

Great! Try running your script again, …and it still won't run, because document isn't defined. We're not really on the web in a browser, but we can fix that with JSDOM.

3. Add JSDOM

You should add jsdom to your project. You can't just import it and have it be global—it's designed to provide an instance of Window and such that you can pass around.

So, you should add a new file like "global-jsdom.ts" to make it global:

import * as jsdom from 'jsdom';

const j = new jsdom.JSDOM(undefined, {
  // Many APIs are confused without being "on a real URL"
  url: 'http://localhost',
  // This adds dummy requestAnimationFrame and friends
  pretendToBeVisual: true,
});

// We need to add everything on JSDOM's window object to global scope.
// We don't add anything starting with _, or anything that's already there.
Object.getOwnPropertyNames(j.window)
    .filter((k) => !k.startsWith('_') && !(k in global))
    .forEach((k) => global[k] = j.window[k])

// Finally, tell React 18+ that we are not really a browser.
global.IS_REACT_ACT_ENVIRONMENT = true;

There's a few lines there but basically it creates a JSDOM and attaches it to the page. You should not be importing this anywhere but in tests.

Add the import to your test file:

import './global-jsdom';

If you build the test now, you might be in business… but it's likely esbuild or Node will complain about dependencies. Let's take a look.

4. Check your build

We need to update our build command a bit before running the test:

$ esbuild test.tsx --bundle --format=esm --outfile=_test.js \
      --platform=node \
      --external:jsdom
$ node _test.js

The big change here is that as we're using Node's built-in testing library, and JSDOM uses parts of Node, we need to set --platform:node. We also need to mark jsdom as external: it uses some tricky loading code to avoid loading e.g., its HTML <canvas> polyfill if it's not available, and esbuild (maybe others) will try to bundle that rather than letting that tricky code live. (You can add the canvas package to fix this, but it needs a boatload of native dependencies to work. Avoid if you can.)

5. Success!

Hopefully you'll see the testing library do its thing. My output looks something like:

$ esbuild --bundle code-test.tsx --platform=node --format=esm --external:jsdom --outfile=_test.js && node _test.js

  _test.js  1.6mb ⚠️

⚡ Done in 54ms
(node:3855) ExperimentalWarning: The test runner is an experimental feature. This feature could change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
TAP version 13
ok 1 - test component
  ---
  duration_ms: 0.010834917
  ...
1..1
# tests 1
# pass 1
# fail 0
# skipped 0
# todo 0
# duration_ms 0.22451975

…the important part being # pass 1, which means the test worked.

6. Cleanup and helpers

Our library works fine, but there's a big omission from Node's built-in testing library: it won't clean up for us. What this means if that if we run multiple tests in a row, then our JSDOM-created-DOM will get polluted with the output from each individual test.

We can fix this pretty quickly by doing this:

// update our import to include cleanup
import { render, cleanup } from '@testing-library/react';

test('test component', () => {
  cleanup();  // always cleanup first

  const result = render(...);
  assert.strictEqual(result.getByTestId('hold').textContent, 'Sam');
});

But this is a bit annoying to do every time. We might be better off defining a helper in a new file—perhaps throwing in the "global-jsdom.ts" file for good measure—like this:

import './global-jsdom';  // just have to import this _somewhere_
import test from 'node:test';
import { cleanup } from '@testing-library/react';
export { render } from '@testing-library/react';

export const reactTest = (name, fn) => {
  return test(name, () => {
    cleanup();
    return fn();
  });
};

And then you can use that helper, all at once, like this:

import React from 'react';
import { reactTest, render } from './react-test';
import assert from 'node:assert';

reactTest('test component', () => {
  const result = render(...);
  assert.strictEqual(result.getByTestId('hold').textContent, 'Sam');
});

reactTest('test something else', () => {
  const result = render(...);
  assert.strictEqual(...);
});

Hooray! 🥳

Bonus Tips

Context: In my (P)react projects, I tend to have a helper like renderForTest which often sets up a number of context providers that components under test might expect. A good example might be providing flags, or a faked out data provider. So rather than calling render directly, you'd do something like:

export const renderForTest = (children) => {
  // you might need to wrap in the render() method from
  // '@testing-library/react' depending on your use case!
  return <>
    <FakeFooProvider>
      <FlagsProvider flags={{ environment: 'test' }}>
        {children}
      </FlagsProvider>
    </FakeFooProvider>
  </>;
};

You're basically just making sure that your code, which might look for context to source things like flags or other types, always has access to that—perhaps through a provider of a 'fake'.

Mocking: Mocking is hard! I haven't got a complete answer here. One strong advantage of using jest is that it uses CJS by default, and can more easily mock things out. If you're using ESM to build, it's hard or possible impossible to swap out your dependencies. Go on, have a try:

import * as allMethods from 'network-tool';
allMethods.doNetworkThing = () => { ... };
// TypeError: Cannot assign to read only property 'doNetworkThing' of object '[object Module]'

In a 🌈 perfect world 🌈 of abstractions, mocks are unnessecary—you should be replacing e.g., a context object or helper class at once to catch all external API calls. But the reality is any code is going to do various calls to fetch() or whatever.

So, yeah.

If this was important to my projects, I'd probably:

• find all methods which get external data
• make my code import them from an internal location
• allow that internal location to swap them for mocks

The naïve way to do this looks like this helper:

const isUnderTest = ...;  // maybe check process.env.SOMETHING ?
const fetch = (isUnderTest ? mockedFetch : globalThis.fetch);
export { fetch };

…this could be simplified with conditional exports, but that's a different post. 📬

Done

That's it. I hope you're writing unit tests as we speak.

If you want to learn more about writing React tests, then I suggest:

• Looking at the result type returned by the above render() method—you'll want to use it to find elements, and check their state
• Reading about user-event, which helps you click on things or type data

You can get a huge amount of benefit out of writing unit tests for components without a real browser, and I hope you'll give it a go. 🌇