Picture the scene. You've run into a type-level problem in your application, and you just want to suppress the error for now and come back later to resolve it. You know (via tests) that the value works, you just need to please Typescript temporarily so you can move forward...

interface Args {
  selector: string;
  element: HTMLElement
}

function matches({selector, element}: Args) {

}

matches({ selector: 120, element: document.body })
                    ^^^
Type  number  is not assignable to type  string 

• ✅ Starting with a correct example - this should be a Typescript error. The property selector of Args has the type string, but we're passing a number. Nothing too interesting here, but we'd like to silence that error somehow.

Line-level error silencing @ts-expect-error / @ts-ignore

A common technique is to throw a quick @ts-expect-error down, and then annotate the comment with a link to a ticketing system. The idea is that it's a searchable thing in the codebase and will be worked on when time allows. In the meantime it provides a single place for others to read up on the reasoning.

For the remainder of this post I'll refer to @ts-expect-error and @ts-ignore interchangeably. For what I'm describing they are equal.

function matches({selector, element}: { selector: string; element: HTMLElement }) {

}

// @ts-expect-error - https://example.com/ticket/123
matches({ selector: 120, element: document.body })

• This silences the error from the subsequent line, and we're linking to a 'cleanup' task that the next developer can view.

On the surface, this looks good, it seems like this feature from Typescript is specifically built for this scenario. After all, libraries change, Typescript upgrades, your app evolves... sometimes we just need to silence an error and move on.

But, is this really the best way to do that?

Exploring the gotchas

So, what can go wrong with a seemingly harmless @ts-expect-error?

The following is nowhere near an exhaustive list, it's just 7 individual examples I could think of, all based around the single topic of calling a function.

BTW - if I was able to find this many, on a single Javascript construct (a function call), just imagine how many actual cases there would be in any modern Typescript codebase 🤯

1️⃣ A 'typo' on the property name is allowed 😭

// @ts-expect-error - https://example.com/ticket/123
matches({ selectar: 120, element: document.body })

• ❌ OOPS! we made a typo, selectar instead of selector (did you spot it? 👀)
• Now Typescript will allow this mistake, because of the line-level @ts-expect-error
• 😭 We only wanted to ignore the type of the selector field, not the field name itself!

2️⃣ Type-checking on other properties is impacted 😭

// @ts-expect-error - https://example.com/ticket/123
matches({ selector: 120, element: 'lol!' })

• ❌ OOPS! element should have the type HTMLElement, but we passed a string by mistake!
• 😭 We only wanted to ignore value of the selector field, not the types other properties!

3️⃣ Typos on other property names are allowed 😭

// @ts-expect-error
matches({ selector: 120, elemant: document.body })

• ❌ OOPS! another typo, this time we spelt elemant where it should be element.
• Even though the type is correct in this instance, HTMLElement, it can still cause runtime bugs since the name is now wrong!

4️⃣ Absolutely anything will be allowed as a parameter 😭

// @ts-expect-error
matches(Infinity)

• ❌ OOPS! this is wrong on so many levels - the line-level @ts-expect-error is effectively switching off the type-checker, risking all sorts of runtime bugs.

Localised @ts-expect-error

Hopefully you're sufficiently convinced already about the dangers of @ts-expect-error when applied to entire lines of code.

I only gave a tiny example of a really simple function, with a couple of ways of calling it. With that alone we were already able to identify 4 places where unrelated bugs could creep in.

So, you might be wondering if a more localised application of the technique could work?

The first thing I tried was breaking object properties and function parameters onto separate lines. It seemed like a nice middle ground.

I was very wrong.

As a refresher, this is correct behaviour

interface Args {
  selector: string
  element: HTMLElement
}

function matches({ selector, element }: Args) {}

matches({
  selector: 120,
            ^^^
Argument of type "number" is not assignable to parameter of type "string"
  element: document.body,
})

• We're still calling the function with an object that has 2 properties, but now we've split it over 2 separate lines.
• ✅ 120 has the type number, where we need a string, so Typescript is giving a helpful error. All good.

But...

5️⃣ It still allows a typo on the property name 😭

matches({
  // @ts-expect-error
  selectar: 120,
  element: document.body,
})

• ❌ OOPS! As before, we only wanted to ignore the type of the selector field, but we've expanded the blast-radius and now a simple typo on the property name will be ignored 😭

6️⃣ You can't apply it to an object value only 😭

It would be nice, if you could go one step further and have @ts-expect-error apply to a value only, wouldn't it...

matches({
  selector:
    // @ts-expect-error
    120,
  element: document.body,
})

• Now we've split the key, selector, and it's value, 120, onto separate lines, in an attempt to silence the error at the value level only.
• This doesn't work though 😭. The value 120 in isolation can never be 'invalid', it's only when considered as an assignable types to the selector field that it can be incorrect.
• We do get a Typescript error here, but just to tell us that the directive is unused, which brings yet more confusion.

matches({
  selector:
    // @ts-expect-error
    Unused '@ts-expect-error' directive.
    120,
  element: document.body,
})

7️⃣ It affects subsequent parameters 😭

So far we've focussed on the impact @ts-expect-error or @ts-ignore can have on a single, object parameter. As if those examples were not enough, it gets even worse when we look at functions that take more than 1 argument.

Let's take a look at a 'correct' example first:

function matchesV2(selector: string, kind: 'css' | 'xpath') {

}

matchesV2(120, 'css')
          ^^^
Argument of type  number  is not assignable to parameter of type  string

• ✅ Now we're calling a function that accepts 2 parameters - and because the first has the type string, Typescript is correctly giving us the error we expect when we try to provide 120.

So, now consider trying to 'silence' this error as before

matchesV2(
  // @ts-expect-error
  120,
  'oops!',
)

• At first, it looks ok. We want @ts-expect-error to only apply to the very next parameter - silencing the error relating to giving 120 when a string was expected
• But, ❌ OOPS! we've accidentally affected the second parameter too!
  • kind, in the function signature, denotes a union type with 2 members, the literal types "css" and "xpath", but we're able to provide "oops!".
• This is terrible! Having a single @ts-expect-error on just 1 of the parameters in the function call is having an impact on subsequent parameters too!

This gets even more confusing/error-prone when you consider that preceding parameters in this style would be type-checked.

Consider another example, this time with 3 arguments.

function matchesV3(input: string, selector: string, kind: 'css' | 'xpath') {}

matchesV3(
  {},
  // @ts-expect-error
  120,
  'oops!',
)

• Notice how all 3 of the parameters in that function call are incorrect.
• line 4, has the type {}, where a string is expected. Typescript will check this ✅
• line 5, our usual example, is marked @ts-expect-error, Typescript will allow this, as expected ✅
• line 6, ❌ OOPS! Again the parameter given for kind should only be one of "css" or "xpath", but "oops!" is allowed 😭

What to do instead

To keep it brief, cast to any and move on - but do so in the most localised way possible.

❌ Before, line-level @ts-expect-error

// @ts-expect-error - fixme: example.com/ticket/123
matches({ selector: 120, element: document.body })

✅ After, localised cast to any in Typescript

matches({
  selector: 120 as any /** fixme: example.com/ticket/123 */,
  element: document.body,
})

✅ After, localised cast to any in JSDoc

Note the surrounding () parens on the value - this is a requirement.

matches({
  selector: /** @type {any} fixme: example.com/ticket/123 */(120),
  element: document.body
})

If you find it messy having type assertions and comments inline like this, you can make it even more explicit with a re-assignment + type declaration as a separate statement.

let temp: any = 120 /** fixme: example.com/ticket/123 */

// now call the function as before, without the noise
matches({ selector: temp, element: document.body })

It will work with as any here too:

let temp = 120 as any /** fixme: example.com/ticket/123 */

// now call the function as before, without the noise
matches({ selector: temp, element: document.body })

JSDoc

let temp = /** @type {any} fixme: example.com/ticket/123 */(120)

// now call the function as before, without the noise
matches({ selector: temp, element: document.body })

Works for multiple parameters too:

function matchesV2(selector: string, kind: 'css' | 'xpath') {}

-// @ts-expect-error - fixme: example.com/ticket/123
matchesV2(
-  120,
+  120 as any /** fixme: example.com/ticket/123 */,
  'css'
)

JSDoc

function matchesV2(selector: string, kind: 'css' | 'xpath') {}

matchesV2(
- 120,
+ /** @type {any} fixme: example.com/ticket/123 */(120),
  'css'
)

All examples above share the same benefits - they all silence the Typescript errors in a way that avoids unintended side effects 👌.

Summary

@ts-expect-error was designed for test-case scenarios - where you are deliberately giving an incorrect type and what to ensure the type-checker is aware of it. Use it for that, only.

@ts-ignore does operate slightly differently in some of the examples given above - but not differently enough for me to document it in this post. Regardless it's still absolutely full of odd behaviours and has unintended side effects, so I highly discourage its use too.

Instead of these brute-force approaches, use localised casting instead.

@ts-expect-error and @ts-ignore, in both regular Typescript and with JSDoc, should be seen as an absolute last resort. You must have tried all other ways of casting values before ever resorting to them.

The decision to inline types directly into method signatures vs extracting into an interface or type is a common discussion point at the moment.

The inline vs interface vs type debate very much focuses on the RHS (right-hand-side) of the parameter definition - but today I'd like us to consider a dangerous pattern on the LHF side instead.

First though, a quick refresher on those terms:

Types inline

function matches({ element, xpath }: { element: HTMLElement, xpath: string}): boolean {}

Separate Interface

interface Props {
    element: HTMLElement;
    xpath: string;
}
function matches({ element, xpath }: Props): boolean {}

Separate Type

type Props = {
    element: HTMLElement;
    xpath: string;
}
function matches({ element, xpath }: Props): boolean {}

And by RHS/LHS I'm referring to the sides separated by the :

function matches({ element, xpath }: Props): boolean {
                 ^^^^^^^^^^^^^^^^^^  ^^^^^
                 LHS                 RHS
}

With that clarification out of the way, let get into it.

The first implementation

Our example is a function that just takes a single parameter, and applies destructuring inline.

Both element and xpath are required properties on the first parameter to this function, so callers must provide them both.

interface Props {
    element: HTMLElement;
    xpath: string
}

function matches({ element, xpath }: Props): boolean {
  return document
    .evaluate(xpath, element, null, XPathResult.BOOLEAN_TYPE, null)
    .booleanValue;
}

• Note how the first and only parameter here is a destructuring assignment. It's often thought of as 'unpacking' the element and xpath properties, but as we'll see later I don't find this framing useful.

Now, before we start to find bugs, let's quickly break down what parameter position destructuring assignments actually represent "behind the scenes".

If we remove it from the signature and re-create the functionality directly in the function body it helps to reveal some hidden elements

interface Props {
    element: HTMLElement;
    xpath: string
}

function matches(): boolean {
  let { element, xpath }: Props = arguments[0];
  return document
    .evaluate(xpath, element, null, XPathResult.BOOLEAN_TYPE, null)
    .booleanValue;
}

• We've removed everything from the function signature for clarity
• We've introduced let to make it crystal clear that destructuring is an assignment. That is, we're creating 2 new bindings in this function's scope, element and xpath

We've kept type declaration : Props in place, to mimic what was in the signature, and arguments[0] just gives access to the first parameter.

const { element, xpath }: Props = arguments[0];

• You can read this line now as
  • create new bindings element and xpath with types that match the corresponding types in Props
  • for example, binding element has type Props['element'], and xpath has type Props['xpath]

Nothing too exciting or surprising here. Typescript will do it's job and the new bindings can be used safely.

It all changes with defaults, though

Let's evolve our function to now also support regular CSS selectors. We'll change xpath to selector, and because xpath and css selectors are not interchangeable, we want a new property to help differentiate between them.

We'll call that new property kind, and we'll use a union of 2 literal types "xpath" | "css" as a poor man's enum.

More importantly though, because we already have a bunch of consumers of this function that we don't want to change, we'll introduce a default value for kind and make it optional.

interface Props {
    element: HTMLElement;
-   xpath: string
+   selector: string
+   kind?: 'xpath' | 'css'
}

-function matches({ element, xpath }: Props): boolean {
+function matches({ element, selector, kind = "xpath" }: Props): boolean {

}

• Note: This is still perfectly type-safe ✅. Typescript will verify that any default value provided for kind has to be assignable to Props['kind'], which expands to "xpath" | "css" in our case.

Let's see what happens if we try to assign a different default value - something other than "xpath" | "css". (broken onto multiple lines for clarity):

function matches({
    element,
    xpath,
    kind = "nope!"
           ^^^^^^^
Type "nope!" is not assignable to type "xpath" | "css"
}: Props): boolean {

}

• ✅ Nice! This is what we want - if we provide a default value within the destructuring like this, we want to ensure it can only be a value assignable to the expected type. "nope!" fails that test, so Typescript prevents the bug!

The next evolution, cleaning up the function signature.

As time goes on, more params are added and someone decides to drop the destructing from the function signature and instead do it as the first statement in the function body

interface Props {
    element: HTMLElement;
    xpath: string
    kind?: 'css' | 'xpath'
}

function matches(props: Props): boolean {
    const {
        element,
        xpath,
        kind = "xpath"
    } = props;

    // snip
}

• Ahhh! a breath of fresh air - having just the parameter name props alongside it's type Props leave the function signature in a great place. Docs can be added to the interface/type and the amount of values can grow at will without becoming difficult to read/reason about
• We've all seen crazy destructuring patterns that end up hogging the screen space in the function signatures - so why wouldn't you do this?

Well, just wait (and hold my 🍻)...

There's a 'trap' you can fall into when combining types, destructuring and default values.

I've used Typescript since it was released, and have fallen for this on numerous occasions!

interface Props {
    element: HTMLElement;
    xpath: string
    kind?: 'css' | 'xpath'
}

function matches(props: Props): boolean {
    const {
        element,
        xpath,
-       kind = "xpath"
+       kind = "this will not error!"
    } = props;
}

• 😱😱😱 This change does NOT cause a Typescript error!
• We only wanted to allow "css" | "xpath", but "this will not error!" is being allowed here!
• This affects more than just literal types - but this a good example since so many programming patterns in Typescript make heavy use of unions, and narrowing them.
• Now, depending on how you go on to use kind, it may or may not be a big bug in your program. But the simple fact that Typescript cannot prevent you setting an incorrect default value in this way concerns me!

👀 So, even though props is marked as type Props, the type-safety doesn't seem to follow though to the props.kind property - why?

Lets de-sugar the destructuring - it might help us understand how this hole in type-safety comes around.

interface Props {
    element: HTMLElement;
    selector: string
    kind?: 'css' | 'xpath'
}

function matches(props: Props): boolean {
    const element = props.element;
    const selector = props.selector;
    const kind = props.kind ?? "foooo";
}

• This is a good-enough approximation of what the previous destructuring was doing.
• This highlighted line is now effectively saying:
  • create a new binding kind
  • with the type: Props['kind'] | "foooo"
  • which expands out to "xpath" | "css" | "foooo"

And that explains why Typescript won't error here - the new binding kind is just that - a new binding, it's not required to have overlap with Props['kind'] - it's just that Props['kind'] contributes a type that kind could be assigned to.

So we've essentially disconnected props.kind from the local binding kind. They have a loose relationship, but not the kind that will help us write correct programs. 😭

If we wanted to maintain the type-safety with this pattern, (still using this long-hand demo), we'd have to apply type declarations for each property 🤮

interface Props {
    element: HTMLElement;
    selector: string
    kind?: 'css' | 'xpath'
}

function matches(props: Props): boolean {
    const element = props.element;
    const selector = props.selector;
-   const kind = props.kind ?? "foooo";
+   const kind: Props['kind'] = props.kind ?? "foooo";
}

• ✅ By applying that type declaration, const kind: Props['kind'], Typescript will check all possible values in the assignment and error if a type is invalid. This means "fooo" is now rejected.
• The same thing applies for the other properties too, omitted here.

Also, if we wanted to apply the same 'fix' to the destructuring version, it would look like this:

interface Props {
    element: HTMLElement;
    xpath: string
    kind: 'xpath' | 'css'
}

function matches(props: Props): boolean {
    const {
        element,
        xpath,
        kind = "foooo"
-    } = props;
+    }: Props = props;
}

• Here we're re-adding the full type declaration back in, directly after the closing } from the destructuring, making it safe again.

This whole thing is becoming rather unsatisfactory though - it's so easy to forget to add these declarations, and no amount of strict Typescript or ESLint settings can help us here 😭

Summary:

This is not just limited to function signatures - that's a really common case, but the following snippet is equally dangerous/error-prone.

interface Props {
    xpath: string
    kind?: 'xpath' | 'css'
}

const props: Props = { kind: "css", xpath: "..." };

const {
    kind = "a"
} = props;

• 🧨 As before, Typescript cannot help you here - this 'type mistake' can be perfectly explained with the long-hand de-sugaring as shown above.
• Remember this line translates to: 'create a new binding kind with type "xpath" | "css" | "a"' - which is not what you're probably intending.

This is not a 'bug' in Typescript, or a problem with JavaScript really - I just view it as an easy mistake to make, something to watch out for.

Going forward I'm personally going to use the inline-destructing pattern more - even though I don't like noisy function signatures. The ability to prevent an entire class of type-safety bugs is just too appealing.

Regardless of which strategy you choose, having a better understanding of the semantics of destructuring assignments could help you identify/fix bugs sooner 🤞

Finally, the next time you encounter people discussing what happens on the RHS of that :, remember that the LHS is far more important for program correctness, so don't leave it out of the conversation! 👋

TRU (Time to Reviewable URL) is the amount of time it takes for a code change to be reflected onto a public URL.

Note: Not producing reviewable URLs yet? Don't worry, there's still some valuable information in this post that will help lead you there.

How to measure TRU?

Your TRU score is measured in minutes/seconds. It's a timer that is triggered by a code change such as a pull request, and it ends when that change can be reviewed by others.

Example: if your CI process follows the common pattern of performing some static analysis, then building your app, followed by tests, it's not uncommon to see a timeline like this:

Note: These numbers are very conservative, I've seen much higher ones in real applications, but we'll use this rounded down '10 minutes in CI' as a way to frame our improvements.

The green block at the end of the pipeline is where a public URL is made available to others, therefore, in this setup: TRU = 10+ min.

Converting that fact (of deploying to a public URL in 10+ min) into a measurable metric (TRU) helps start a conversation about how to improve it.

So, what's a good TRU?

The 10+ min example above is not a good TRU. It might be acceptable as a first step - for example if you're only just embarking on the concept of Preview URLs, but in reality we all know of CI processes that far exceed 10+ min.

We need to aim higher, for a TRU of less than 1 minute

Getting to this point would be a game-changing improvement to your organization. Going from opened PR to a public URL in less than 1 minute, creates entirely different workflows.

The following advice in this post is admittedly easier to enact on greenfield projects, where you have more freedom to choose your tools and processes. But, even on those projects where you think a one minute build is absurdly unrealistic, you can still work to reduce your TRU using the tips and tricks I mention along the way.

Why is a faster TRU better though?

Faster delivery, lower costs, easier maintenance and a better user experience.

Optimising for a faster TRU, especially in a team environment, creates a culture that values deliverable software, deeper collaboration (through transparency) and better engineering practices overall.

• If your TRU is trending downwards (eg: towards faster deploys) you are quite literally speeding up every aspect of your software delivery pipeline. Getting eyes on your work sooner than you could before, means you not only have the opportunity to catch bugs and regressions sooner, but you can also solicit reviews from peers earlier in the project's lifecycle too. This will ultimately lead to better quality software, delivered in less time.
• Having a low TRU is also a strong indicator that you've fought for low-complexity - both in your application code but also in your delivery processes as a whole. Low-complexity codebases and processes are easier to maintain and adapt in the long term.
• If you have a low TRU, it probably means your CI bills are lower too since it'll be doing less work for each change.

The inverse of those benefits tells a bleaker, but more accurate picture based on what I've seen in Frontend-heavy applications.

• If your TRU is trending upwards (eg: towards longer deploys) it normally means your team is becoming slower at delivering changes overall. If it's taking longer to deploy a preview URL than it did before, then the changes that caused that slowdown are directly impacting the speed in which reviews can occur. That, in turn, will cause projects to take longer to complete than they did in the past.
• If the main culprit of a high TRU is the build time, that tends to point to a project that has a high dependency count along with many 'layers' that make up the application, and its associated tools. Your build/CI pipeline is doing a lot of heavy work in this scenario, which is a symptom of not prioritizing simple tools and processes.
• Projects in this state tend to be more challenging to maintain, adapt and upgrade due to the interwoven dependency graphs, adding further delays.

Who benefits from a faster TRU?

Managers will appreciate a faster TRU—having changes ready to review more quickly will obviously speed up projects. You can fit more iterations and deployments into a day, and so your work will progress more quickly.

Collaboration with Designers, UX and Accessibility folk will be more productive too. If someone can review a change 40 seconds after you made it, your combined efforts will pay off sooner.

Meanwhile for the engineers, they will feel liberated and more confident to make changes at a faster pace. They will enjoy the burden of a long delivery pipeline being lifted, and can instead focus on making your product better for users.

Speaking of which, the most important beneficiary of all will be: your users.

Spending engineering time on reducing your TRU will naturally lead to lighter, more nimble software. If you actively work to lower your build and deployment times, you'll find that it rules out a whole category of processes, tool and dependencies automatically. Namely, the slow and bloated ones.

Lighter, faster software is accessible to a broader audience than the heavier, slower kind. It'll run better, for longer too, on devices of all kinds.

Ok, how do we get there?

We need a faster build process, with a more controlled environment and a prioritized preview deployment. Those are the 3 steps I am highlighting in this post.

Tough decisions will need to be made, and some real engineering will need to occur.

So let's go through the steps in order of difficulty:

Step 1: A fast build process

Everything hinges on this first step—without it, steps 2 and 3 won't have the same compounding effect.

Projects that never make it to a fast TRU are most often hamstrung by how long their bundlers run for in CI, so we need to aim for a build process that takes just a second or two.

Tools like esbuild can do an awful lot in a second or two, and they don't tend to lead you down the path I've seen so often—where a well-meant setup can start to crawl in the build times.

A none-exhaustive list of rules you can apply, regardless of which specific tool you choose:

• Choose a modern, fast bundler - one that doesn't require a complex dependency graph of loaders/processors.
• Separate the bundling and building from all linting and formatting
• Favor micro libraries and frameworks that are closer to the web platform (lit, svelte, preact etc.)
• For styling, opt for any process that results in regular CSS files and CSS classnames - loaded with <link /> tags
• Use a preview "build target" as an opportunity to avoid expensive processing (more on this in Step 2)

If you have the luxury of choosing tools and processes on a new application, figure out how far you can get with just esbuild (or similar).

Ensure you are separating the generation of production assets from any type-checking, linting or formatting. Sure, have ESLint/TypeScript running in parallel if you'd like, but the 'build' should not be not much more than crawling through your entry points and producing JS files on the other side.

Next, limit your dependencies massively, and audit them continuously. For React devs - try building on a basic setup of just Preact, Preact Signals + CSS modules. You might just be amazed how far you can get.

• Note: If you go down this route - I'd recommend against an alias of preact/compat -> React. I'd just import preact directly. Pretending to be React gives the illusion that React-specific packages will 'just work.' I've found issues with this approach, and by just using Preact directly I've seen fewer bugs and fewer temptations to bring in packages that affect build times.
  • Sub-Note: Not choosing React (or aliasing with preact/compat) also has the nice side-effect of encouraging you to seek out libraries that are framework-agnostic by default. Those tend to be lighter and more focussed on the web-platform as a default.

For styling, avoid any CSS-in-JS solutions. There's too much work needed to process them and tools like esbuild can handle raw CSS + CSS module imports anyway. Let these tools produce a regular old CSS file, and you can load it into your HTML just how the browsers prefer it.

import styles from "./app.module.css";

function App() {
  // this is fine...
  return <div class={styles.root}>...</div>
}

<!-- because you'll still end up with this, in your HTML (not JS) -->
<link href="styles.css" rel="stylesheet" />

For those outside the React world, or for those looking to avoid JSX too, take a close look at Svelte or Lit. Whichever you choose, if the build time is going to be longer than a few seconds, then it's not really compatible with a low TRU and should be avoided.

Now, regardless of which framework/bundler you choose, always consider what can be excluded from your build process. For example, is it really necessary for all your assets to go through a bundler's pipeline? Is there anything you can pre-process with other tools and just place in the public folder like the old days?

What about that long, slow translation process—can that be done separately? Perhaps in the preview build (detailed next) you could configure the application to load a translation file at runtime over fetch (from the public folder)?. That would avoid executing a really complex build-time flow in the bundler (that often ends up including all locales—I've made that mistake before!)

These are just ideas—all of which in isolation might not make much difference. But, as a whole, employing this style of engineering discipline will lead you down the path to success.

If you've managed to convince your team that this is a worthwhile pursuit, you're already most of the way there, and you're standing out from the crowd. If your bundler process is just a second or two, you're never going to feel burdened by it.

The next step, is to create a more Controlled Environment.

Step 2: Controlled Environment

A Controlled Environment is a way of running your application with pre-defined, deterministic states.

It could include things like mocked data. That helps to avoid UX and Design work from needing slow services that are complicated to setup (like API backends) in the preview environment. It might even have some logic baked in to present the application in a known state for testing. No matter which level you reach though, the key word here is determinism.

When everyone visiting a specially configured URL is experiencing the same thing, reviews and sign-off will be faster.

Browser-based tests can use the configured URLs too—making them faster and less flaky. It's reasonable to assume you can reduce the length of your in-browser tests by 10x if you employ stricter rules around a controlled environment.

Having application states triggered by shareable URLs, as an example of a Controlled Environment, will enable more accurate collaboration. Then re-using those URLs in automated tests gives a greater confidence that the CI process will go green eventually. (This overlap between the Preview URL and your tests becomes crucial in Step 3, where we'll be seeking human reviews long before the automated tests have finished).

As always, the following examples are just things I've seen work well - so don't get too hung up on the exact tools or techniques—instead remain focussed on the goal of controlling your environment.

Creating a Controlled Environment with Build Targets

In other programming environments, the use of a 'build target' is a familiar concept. From a single codebase, often multiple build artifacts will be produced—each tailored to the environment in which they'll run. This is often (but not always) achieved with source-code annotations, like an attribute above a function, or some kind of special syntax.

You can use this kind of technique to produce a special preview build of your application that is pre-loaded with knowledge of how to reproduce certain states. Controlling the external boundaries of your application is a good practice anyway - and this technique just leans into it.

To make this work, we'll need basic bundler support and a single abstraction around whatever service you want to control.

Bundler support

Since I mentioned esbuild already, I'll keep the examples specific to it. Other bundlers will have different ways of achieving the same output.

So, for brevity, let's just assume your application talks to it's backend over fetch. To load a different implementation in the preview build, we can use a label like $PREVIEW: <expr>, and then configure esbuild to strip it out of the production builds.

import mockFetcher from "./mocks.js";

// the default
const fetcher = globalThis.fetch;

// using a JavaScript label as something that the
// build can choose to leave in, or strip out.
$PREVIEW: fetcher = mockFetcher

Now we can configure esbuild to drop those $PREVIEW labels by default - this will act as the "production environment".

// the default, for the production builds
esbuild.buildSync({
   ...opts,
   dropLabels: ['$PREVIEW']
})

Then, to create the preview build we just omit the $PREVIEW label.

// when --target=preview
esbuild.buildSync({
   ...opts,
   dropLabels: []
})

On its own, this doesn't seem too useful, but in the case of this esbuild-specific idea, it will also strip the import statement of ./mocks.js when unused (in the production build), meaning you have a safe entry point in JS, where you can go further than plain mocks.

You can now add logic, timers, JSON files and most importantly, altering the preview behavior based on URL Search Params.

Making use of the URL

Now that we have an idea of what it means to create a 'preview' build - we can start to get creative about how we respond to requests and how other side-effecting services affect our application.

Let's look at a practical example, where a state-based bug has been occurring if a particular API request is delayed.

In this workflow, we'd always start from the URL - thinking about how this particular bug can be reproduced if given a set of parameters are present. Let's say we decide to add ?mock.api.delay=1000. Then, inside the mock implementation in ./mocks.js we can detect it easily and adjust how we'd respond.

// in mocks.js, not present in the production build
const url = new URL(location.href);
const delayOverride = url.searchParams.get('mock.api.delay');

// now use 'delayOverride' if it's not null to fake a slower response

Note: Mock Service Worker could be a good option here too, of course.

The implementation is left up to the reader, but the bigger picture here is that mock responses alone are sometimes not enough, and we'll often want to add some logic too.

Once you get into the habit of making more and more states representable with sharable URL params like this, you'll notice that people start sharing multiple review links when making changes, each tailored to highlight a particular state.

Those I've helped to understand and adopt these practices are full of praise for the boost in productivity.

It turns out that this is an excellent way to run UI tests too.

I've seen testing setups of all shapes and sizes. From hour-long E2E test suites that nobody dares to touch, to an over-reliance on unit-tests (and the fake confidence they bring) all the way through to fine-grained component testing where everything works in isolation (but not together). My take, after all these years, is to favor in-application testing, but with a strict rule around controlling the environment.

With the correct level of control in place, it's a joy to work with tools like Playwright - with tests that are somewhere between E2E and integration. If each test fully loads the application, but it's configured to load the preview build, then we can use the same URL search params that reviewers are using in the public URLs. However, now we're using them as test cases.

This creates a really nice development cycle where your tests are fast, predictable and end up being a library of URLs to reference later.

Note: I'm deliberately omitting information about how any data/service mocking is implemented. There are lots of ways to achieve it, each with their own benefits/tradeoffs. Instead I just want to emphasise the idea of sharing URLs with previews and tests.

Make the preview URLs load the preview build

Now the easy part. Once you've figured out your bundler's preferred way to create a specialized 'preview' build like the prior example, you just need to ensure that your CI process knows when to use it. When deploying to the preview URLs, always build the "preview" target. Otherwise, build as normal.

If you've gotten to this point in the advice, you might already have a 1 second bundler process, along with a special preview build target all working nicely together. If you do, you're well on the way to a seriously productive project with excellent collaboration.

You'll just want to ensure nothing else in CI is slowing down these preview URLs from deploying...

3: Prioritizing the preview deployment in CI

An often overlooked optimization—don't let other checks/processes delay your preview URLs!

There's no bigger fan of static-analysis and tests than yours truly - both I consider to be mandatory for any team of engineers. But after so many years of participating in this industry, I've come to realize you can have your cake, and eat it too.

You can have discussions with Product Managers and Designers about a Preview URL that was created in seconds, all whilst the 'rest' of the CI checks are occurring in the background.

In the end, you're not going to ship to production without those green check marks anyway, so you might as well get ahead of the game and use that time to have people looking at your work.

Remember, if you've followed the advice from Step 2 - most of your browser-based tests should be running against the preview build too, so you can be confident that reviewers and automated tests are evaluating the same work!

Run a build + Deploy as early as possible

In the 10+ minute example, we saw how the preview URL was only deployed when everything prior completed successfully.

Now, Step 3 of my advice is to free your engineers from the slow-down caused by those other processes, and let a deployment to a preview URL happen as soon as humanly possible.

Because of Step 1 (a faster build process), you don't need to worry about running the build more than once. So, for the sake of getting a really fast TRU and getting eyeballs on your work as soon as possible—why not ensure your processes can handle a concurrent flow that only includes a build + deployment?

Even if your build is 10 seconds, and then your preview deployment is 35 seconds, that means a TRU of 45 seconds is an achievable goal!

Summary

TRU (Time to Reviewable URL) is a metric that you can start tracking immediately. It's a proxy metric that can help to expose the overall health of your software and its delivery pipeline. A team that maintains a fast TRU and continuously looks to improve it, is likely delivering better work, more quickly, than those that do neither.

The 3 Steps I've presented above will get you closer to a fast TRU. It takes tough decisions and solid engineering work, but the rewards are worth it.

The metric can be used to inform engineering decisions. For example, by referring to it when new tools and processes are being proposed. Ask: 'How will this impact our Time to Reviewable URLs?'.

Managers and Tech Leads: Ask your Engineers if there's any low-hanging fruit that can be picked off in the name of reducing your teams' TRU.

Engineers: On greenfield projects, deeply consider which tools, libraries and processes have the highest likelihood of maintaining a low TRU in the long term. Choose lean, choose light.

On brownfield projects: gather your baseline metrics (how long it's taking to deploy right now) and start to paint a picture of where the biggest delays are. Then in downtime, or during a maintenance window, you can work towards lowering your TRU to the benefit of all involved.

Typically, usage of the as keyword in Typescript is frowned upon, for good reason. Type-assertions represent a place in code where you're saying that you know better then tsc. Sometimes you do, often you don't.

Others have written at length on this subject, so I don't want to enumerate the good/bad use-cases again here. Instead, I wanted to highlight a time when it's not only a good idea, but can actually help you design better programs.

Example: XState machine definition

In XState, context is a piece of internal state that you end up accessing from various places, and schema.events represents a union of possible events that this machine accepts.

Of all the things you might want to be 'strongly typed' in your application, internal data and incoming events should be right at the top of the list.

This is why you'll often see the following pattern in use:

const machine = createMachine({
  id: 'dialog',
  context: {} as { id: string; },
  schema: {
    events: {} as
      | { type: "OPEN" }
      | { type: "CLOSE" }
  },
  states: {
    "closed": { on: { "OPEN": "open" } },
    "open": { on: { "CLOSE": "closed" } },
  },
})

• It's just a simple/demo machine definition, we're not focussing on any actual functionality here.
• Note how both properties (the highlighted lines) lines are using {} (empty object) as the values, followed by as ..., that's the type assertion part. The value is just a plain old object, but we're lying to Typescript, and asking it to treat context as though it was { id: string } and schema.events as though it was a union of those two objects.
• The interesting part here, is that we're doing this only to provide types, nothing else.
  • Consumers of this machine will be forced to provide id: string as a context property. ✅
  • Likewise with schema.events - this will ensure anyone sending messages to this machine can only send one of the messages we defined. ✅
• So it's all about defining types, or contracts. We aim to make fault free programs and this kind of code-level documentation that gets enforced by Typescript can help us along that path.

Trying default values instead

Because type-assertions are sometimes frowned up, I wanted to take a moment to consider alternatives ways to handle the typing of that context.id property in the example above.

Hopefully you'll see, that used in the correct places, type-assertions can make a lot of sense. Why? Because we can use them as an alternative to a default value.

So taking an alternative path for illustrative purposes, we could model this problem by using string | null as the type of the id field instead: (undefined would work nicely too, but space.)

const machine = createMachine({
  id: 'dialog',
  context: { id: null } as { id: null | string },
  schema: {
    events: {} as
      | { type: "OPEN" }
      | { type: "CLOSE" }
  },
  states: {
    "closed": { on: { "OPEN": "open" } },
    "open": { on: { "CLOSE": "closed" } },
  },
})

• This highlighted line shows how we can set an initial, or default value for id, using null to represent the absence of the actual string value.

• The part that follows, as { id: null | string }, ensures that Typescript will allow us to assign a string value later

  • Without this, we'd be stuck with only null being an assignable type

• This is quite a nice pattern if a default value makes sense to your particular problem.

  • For instance, perhaps the id is actually unknown until some asynchronous operation has completed. In that case, id can really be null or a string.

• If you find yourself in this kind of situation, then the way we've set this id field up is really accurate. It's null now (the default), but can be also become a string later.

• You'll get help from Typescript too. Whenever you try to use id as a string, you'll be reminded that it could be null, so you'll have to check. Being honest like this about the nullability of a value should prevent some of the most common Javascript bugs (accessing values that are absent). ✅

JSDoc

For completeness, in JSDoc we can achieve the same thing with the following:

createMachine({
  id: 'dialog',
  context: {
    /** @type {string | null} */
    id: null
  },
  schema: {
    events: /** @type {Events} */ ({})
  },
  states: {
    "closed": { on: { "OPEN": "open" } },
    "open": { on: { "CLOSE": "closed" } },
  },
})

When a default value makes no sense

The previous approach, making id have the type string | null, is fine if it's a true reflection of the way your program is structured.

The flip side though, is when you know that your component or state-machine could never have come into existence without an id. In that case making it nullable in the initial context definition is no longer accurate - it's just there to please Typescript.

I've seen this (and done it myself!) on many occasions - they are plenty places in Typescript codebases where a type is 'wider' than it needs to be - a simple ? on a property when it's not actually optional, or like in our example, providing a default for something that actually can never actually take that value.

This kind of problem creates a knock-on effect too. Using wider types than needed, like string | null when just string would've been enough, means that you'll have to keep narrowing it everytime you try to use it.

const [state, send] = MachineContext.useActor()
const id = state.context.id;
//                       ^^ null | string

• Notice how the type from the initial machine definition comes through here - context.id cannot be used directly, even though we know that it can never actually be null due to how the rest of the program is structured.

So, when I am forced to deal with this, I prefer to halt the program, considering it a completely invalid state.

import invariant from "tiny-invariant";

// later
const [state, send] = MachineContext.useActor()
const id = state.context.id;
invariant(typeof id === string, "")

console.log(id)
//          ^^ string

• this highlighted line checks the given condition for truthiness, and will throw an exception if it fails.
• then, thanks to control-flow analysis, subsequent lines can now freely use id as a string, since Typescript knows that's the only type assignable to it.
  • Before this check, id had the type string | null, but the check typeof id === string effectively erases the possibility of it being null, leaving only string ✅

If you are not using something like tiny-invariant, you can cause the same effect on control-flow analysis with a manual throw

-invariant(typeof id === string, "unreachable, id must be a string")
+if (typeof id !== string) throw new Error("unreachable, id must be a string")

Avoiding runtime validation when possible

These runtime checks that only exist to please Typescript are a bit of a necessary evil - they can be used for good, but we should try to recognise which of them are required, and which can be made redundant with a better design.

Side note: I'm not referring to the rise in popularity of tools that verify external data - you should be validating everything that comes into your application anyway, ideally using tools that have a nice integration with Typescript, like Arktype, Zod, Valibot, etc.

In relation to the examples given in this post, a 'better design' would be to prevent using a wider type than needed. In short, that means getting back to the example we opened with, where a blank {} is used, along with a type-assertion to force Typescript into believing our context has the type { id: string }.

-   context: { id: null } as { id: null | string },
+   context: {} as { id: string },

• Because of the way XState works, users of this machine will need to provide a valid context and because we've now removed the null, consumers will understand that a valid id is part of the contract.

Now, the design of the types actually reflects the usage in code - if there's never a way that id can actually be null, then we should strive to avoid it and not resort to a default value of null or undefined.

Avoid colouring your code

The concept of 'colouring' has been spoken about before, often about languages that support async/await. The idea is that the moment you make a function async, you're now forcing the caller of your function to handle the fact that it won't yield a value immediately. They'll have to use APIs or language features to 'wait' for the value, or to 'unpack' it.

Once you alter your code to handle someone else's latency like this, you inevitably have to alter your API too so that your callers know they can no longer expect a result synchronously. It spreads outwards, on and on. Before you know it, functions that have no business being async or knowing anything about program latency can end up being 'coloured' in this way.

Whilst perhaps not to the same degree, I consider the 'width' of types, or the amount of types that are assignable to a value, to also be a form of colouring. If the value has a single assignable type, I'd consider it to be the same colour as a regular synchronous function. In both cases, consumers don't have to deal with the additional domain knowledge - they can just use the functionality as described on the box.

But, if you include too many types, like string | null when just string would have done, you're now forcing other places in the program to have to narrow the type before usage. It's a different colour now, and consumers will need to look up how to deal with your leaked implementation detail - worse, they may even need to change their colour to suit yours!

Summary

Of course, I'm just using this fictional id field and the type string | null as a way to represent the type widening/narrowing problem in a simple, concise way. But, it's the concept that's important - I'm sure you can expand this idea to cover more complicated types that you've worked with.

Is there somewhere you can remove an optional property? Is there a null or undefined value that can be removed altogether with a different program design?

The design of your types has a much larger impact that it first appears. If you're going to spread one colour over another, try to ensure it's deliberate & accurate. If it's just in the name of pleasing Typescript or getting something done in a pinch, then put a todo on it and stick it in the tech debt category 💪.

JSDoc Code Examples for Reference

Whilst the as keyword cannot be used in JSDoc (not valid Javascript), you can achieve the same thing.

// ts
context: {} as { id: string | null; }

// jsdoc
context: /** @type {{id: string | null}} */({})

• note how in the JSDoc example there's an extra () around the {}, this is how you get @type to apply directly to the subsequent expression.

Just like in Typescript, if you want to move your types into separate definitions, you can either use @typedef in the same file

/**
 * @typedef {{type: "OPEN"} | {type: "CLOSE"}} Events
 * @typedef {{id: string}} Context
 */
createMachine({
  id: 'dialog',
  context: /** @type {Context} */({}),
  schema: {
    events: /** @type {Events} */ ({})
  },
  states: {
    "closed": { on: { "OPEN": "open" } },
    "open": { on: { "CLOSE": "closed" } },
  },
})

Or, you can use a .ts file, just ensure you only put types it in:

// types.ts
export type Events =
  | { type: "OPEN" }
  | { type: "CLOSE" }

export interface Context {
  id: string
}

With that types.ts file, you can then import types directly

createMachine({
  id: 'dialog',
-  context: /** @type {Context} */({}),
+  context: /** @type {import("./types.ts").Context} */({}),
  schema: {
-   events: /** @type {Events} */ ({})
+   events: /** @type {import("./types.ts").Events} */ ({})
  },
  states: {
    "closed": { on: { "OPEN": "open" } },
    "open": { on: { "CLOSE": "closed" } },
  },
})

Consider the following type definition:

/**
 * @typedef {'css' | 'xpath'} SelectorKind
 */

This declares a new type alias for a union of the literal types 'css' and 'xpath', it can then be used in parameter position like so:

/**
 * @param {SelectorKind} kind
 * @param {string} selector
 */
function matches(kind, selector) {}

matches('css', '.heading') // ✅
matches('xpath', '.heading') // ✅
matches('oops!', '.heading') // ❌
        ^^^^^^
Argument of type "oops!" is not assignable to parameter of type "css" | "xpath

In a Typescript file, the same thing would be:

type SelectorKind = 'css' | 'xpath'

function matches(kind: SelectorKind, selector: string) {}

They both provide the same level of type-safety + DX (autocomplete), but the JSDoc version suffers from a possible edge-case that I encountered for real recently 👀...

All about the formatting

A common formatting technique to apply when a Typescript codebase starts to grow:

type SelectorKind =
   | 'css'
   | 'xpath'

It's good that Typescript supports the leading | here, it allows these union types to grow and remain nicely aligned 👌

It's even more common when listing out things like events:

type Events =
  | { kind: 'login'; user: string; password: string }
  | { kind: 'logout'; }

Now, trying to apply this back to JSDoc, the first attempt might be:

/**
 * @typedef {
 *    | 'css'
 *    | 'xpath'
 * } SelectorKind
 */

• ❌ oops! We've just introduced a subtle bug!
• Because the very next character following * @typedef { is a new line, it ends up causing SelectorKind to have the type any!

The most worrying part of this potential bug, is how it silently widens the type to any, whilst still keeping the type defined in scope.

It means that any function that previously used SelectorKind before we re-formatted will still appear to be valid, for example:

/**
 * @param {SelectorKind} kind
 * @param {string} selector
 */
function matches(kind, selector) {}

matches('oops!', '.heading')
//      ^^^^^^^ this should be an error, but isn't!

• on line 2, this type reference is still valid - Typescript will ensure we're referring to a type it knows about.
• but, line 7 no longer causes a type-error, even though it did before 😭
• because SelectorKind was accidentally widened to any, matches will now accept any argument - a random string, a number, anything!

To resolve this problem, you just need to ensure you place a character from your type directly after the opening {, for example:

/**
 * @typedef {|
*       'css'
 *    | 'xpath'
 *    | 'abc'
 *    | 'def'
 * } SelectorKind
 */

• 🤢 I added a few more strings to show the value of the alignment, but now the absense of the | to the left of css just makes this even more confusing.

Here's another format:

/**
 * @typedef {'css'
 *    | 'xpath'
 *    | 'abc'
 *    | 'def'
 * } SelectorKind
 */

• This also works, but now we've lost the alignment altogether! 😭

Regardless of what can work though (there is likely more combinations), let's get back to the point of this post...

Why this matters

I think it's dangerous how a single newline character can convert a previously type-safe implementation into one that now has an any hole in it.

My real-world scenario played out as such:

1. I started out with a simple type, and then used it inside a function parameter.
2. Then, I added a few more variants, until the line-length got too long for my liking.
3. So, I split the type onto multiple lines for readability...
4. 💥 silently, Typescript had demoted my union of string literals into any, essentially removing all type-checking.

Other Solutions

(1) Using Typescript files alongside .js

You can retain your no-build setup whilst still benefiting from more elegant type definitions when needed. Just stick to JSDoc and then import from .ts files as needed.

/**
 * @param {import("./types.ts").SelectorKind} kind
 * @param {string} selector
 */
function matches(kind, selector) {}

// types.ts
export type SelectorKind =
   | 'css'
   | 'xpath'

• The trick with this approach is to only ever put types in your Typescript files - this prevents having to transpile anything.
• Now you can format your types without any of the drawbacks seen in @typedef
• No matter the formatting, inside a TS file this type will never be widened to any by mistake 😍.
• Also, if you need to reach for more complex features, like mapped types, you can also place those in the .ts files too. (something you literally cannot do in JSDoc alone)

(2) Deriving Types from JavaScript code:

In simple cases, you may be able to derive these kinds of types directly from Javascript code instead. The example in this post is deliberately small for brevity, but it would be a good example where you could drop the @typedef altogether, for example:

const SELECTOR_KINDS = /** @type {const} */ (['css', 'xpath'])

/**
 * @param {SELECTOR_KINDS[number]} kind
 * @param {string} selector
 */
function matches(kind, selector) {}

• This approach has some nice properties when the types are simple (eg: lists of strings)

It does however, come with its own tradeoffs: get the parens incorrect, and it'll also accidentally widen to any

// ✅ this has the type `readonly ["css", "xpath"]`
const SELECTOR_KINDS = /** @type {const} */ (['css', 'xpath'])

// ❌ this has the type `string[]`
const SELECTOR_KINDS_2 = /** @type {const} */ ['css', 'xpath']

Summary

When working with TypeScript via JSDoc, it can be tempting to reach for patterns you've used or seen in .ts files from other projects.

If adding them inside JavaScript comments feels awkward, consider one of the solutions mentioned above.

A simple rule to apply is as follows: If your types become complex (like unions) and cannot be represented in a single line, consider moving it to a .ts file or deriving it from code instead 👌.

In this previous post I outlined how the Browsersync proxy works: it sends requests to the target url with modified headers and then buffers the response body in memory before applying string replacements.

I had been following the idea of not spending too much time optimizing the Rust version whilst I was deep in development. Being liberal with .clone() and trying to avoid lifetimes where possible was proving very productive. I was getting features completed really quickly and feeling great about the overall direction.

The pressures of a public demo

Getting to feature parity on the proxy feature was an exciting milestone for me since it proves out a lot of the new architectural patterns (more on this in a future post) and I was keen to make a demo 👀.

So, imagine my horror when I spun up a simple example and it turned out to be much slower than the original NodeJS implementation I'd written years ago! 😱😱

So, did I just forget to run cargo build with --release like everyone does?

A common problem that people run into when benchmarking Rust programs (normally on Twitter when promoting an alternative) is that they forget to build in release mode! Even if you've been writing Rust for years, it's easy to forget. I think that's just because the local development story with Rust and cargo is so ergonomic that we just get so used to running cargo run 🤣.

Regardless, in my case this alone didn't help!

So what exactly was slow

In my demo I just wanted to show a localhost server that proxied all requests through to a live website (in the Browsersync style).

GET localhost:3000/ -> GET https://browsersync.io/
GET localhost:3000/css/core.css -> GET https://browsersync.io/css/core.css
... etc

When using https://browsersync.io/ you get a total of just 19 requests (when viewed in the browser).

This was hardly a stress-test, so why the crazy numbers?

Something was wrong here. Even though I hadn't applied any specific optimisations yet, I had expected the Rust version, even in debug mode to far out-perform the NodeJS implementation...

The Importance of Connection Pooling

The short version is that my implementation was creating a new HTTP client inside the main request handler! 🤣

So, for every single HTTP request that my application dealt with, it was spinning up a new thread pool and preparing things behind the scenes to re-use resources where possible. Only for the handler to exit, tearing down all the side effects and then re-creating them immediately on the next request 😱.

No wonder the Rust version was even slower than the NodeJS version!

The problem

Since I was deep in prototyping mode and was thinking more about architecture than individual handlers, I let this slip by:

Imagine an HTTP server being started like this:

#[tokio::main]
async fn main() {
    // snip
    let app = Router::new().nest_service("/", any(handler));
    // snip
}

That's a reasonable way to allow a single service to handle all routes under /. The problem is what occurs within handler

pub async fn handler(req: Request) -> Result<Response, StatusCode> {

    let https = HttpsConnector::new();
    let client = Client::builder(TokioExecutor::new()).build(https);

    // snip: modify the response object

    Ok(client
        .request(req)
        .await
        .map_err(|_| StatusCode::BAD_REQUEST)?
        .into_response())
}

• This async function, handler will be called for every request - HTML, CSS, JS, images, web sockets, everything!
• On lines 3 and 4 we create the http client and it's https connector
• But this happens over and over again with every incoming request 🙈🙈🙈

I was very confident this was the cause of the poor performance 🤣 - so, it was just going to be a case of moving the client creation code out of the handler, and coming up with a way to access the client in the handler.

The solution

Step 1) ensure the client is not re-created on every request. This can be done by pulling it up into main

#[tokio::main]
async fn main() {
+   let https = HttpsConnector::new();
+   let client = Client::builder(TokioExecutor::new()).build(https);
    let app = Router::new().nest_service("/", any(handler));
    // snip
}

Step 2) Next, we need to access that client from within the handler.

Luckily Axum has a really nice way to do this, known as extractors. Extractors allow a type-safe way of accessing various useful things from within your handler functions.

async fn handler(State(client): State<Client>, req: Request) -> Result<Response, StatusCode> {
   // implementation as before.
}

• Notice how we added a new parameter, State(client): State<Client>
• This uses the State extractor along with the fact that parameters in Rust can also be patterns - this allows direct access to the element inside the tuple struct (client in this case).

Step 3) Provide state to the Router

If we tried to run the code at this point we'd get an error stating that our handler cannot be used with the Router configured in main.

This is the type-safe part - each handler contributes to the overall type of the outer Router - so to satify the type checker we need to call .with_state(...) with a type that satisfies all extractors.

We only have 1 of our own (we use Request too, but that's supported already), so it's just a case of making this small change:

#[tokio::main]
async fn main() {
    let https = HttpsConnector::new();
    let client = Client::builder(TokioExecutor::new()).build(https);
-   let app = Router::new().nest_service("/", any(handler));
+   let app = Router::new().nest_service("/", any(handler).with_state(client));
    // snip
}

With that change in place, http connection pooling will work as expected, and the numbers start to look a lot better :)

Summary

The mistake highlighted in this post was a silly one 🙈, and was easily fixed - but it does show how easy it is to crash performance when dealing with network bound workloads.

And there I was, thinking I just needed that simple --release flag 🤣

Notes:

• I omitted some types in snippets above for brevity - have a look at the working demo I made here for details: https://github.com/shakyShane/t-stream/blob/main/https-proxy/src/main.rs
• There are other perf things I looked at too, like swapping Mutex's for RwLock's, but for the type of tool I'm building those are not going to produce much of a difference :)

Creating a new project with https://napi.rs is as easy as:

npm install -g @napi-rs/cli

Followed by...

napi new

... which is great. But I wanted to keep the project within a Cargo Workspace so I made the following changes (using the project name bslive, which stands for Browsersync Live, in case you wondered)

Step 1

Create a new directory at the root level of the project

mkdir bslive

Step 2

Move the following files/folders

src/lib.rs
build.rs
Cargo.toml

into

bslive/src/lib.rs
bslive/build.rs
bslive/Cargo.toml

Should look something like:

Step 3

Now create a new Cargo.toml in the root of the project, to replace the one you just moved

Cargo.toml

workspace.members = ["bslive"]
workspace.resolver = "2"

Step 4

The last is to tell napi where to build from (since it defaults to the root of the project).

In the package.json file, find the scripts section and change both build and build:debug to include the flag --cargo-name <name>

package.json

-   "build": "napi build --platform --release",
+   "build": "napi build --cargo-name bslive --platform --release",

-   "build:debug": "napi build --platform",
+   "build:debug": "napi build --cargo-name bslive --platform",

Done!

Now you can create lots of separate crates in the root of the project (or under a common subdirectory, like crates) and the regular workspace improvements will apply :)

At over 3.2m downloads a month from NPM, https://browsersync.io is still heavily used in the industry. As I continue to modernise the implementation (by working on a Rust port) I came across an interesting case study that became up to 5x faster in a real-world setting, whilst also allowing me to add additional features.

Browsersync's proxy option

One of my favourite features in Browsersync is the ability to run a localhost server, but proxy certain requests through to a 3rd party domain.

browserSync.init({
   proxy: "https://example.com"
});

This will give you back a localhost address that you use to make requests to, like localhost:3000. The NodeJS implementation will then send each request on to the configured proxy target ("https://example.com" in this example), and return the response as normal.

Sounds easy so far...

Actually, it's a bit more complicated than that 🤣. Browsersync wants more control over the response, so that it can replace any links in the markup and inject an HTML snippet.

To do this in node is a bit of pain, and as I've come to realise, very, very slow too.

How the current proxy works

When a request comes in, for something like localhost:3000/index.html, Browsersync needs to forward that onto the proxy target. But before it can do so, it has to mess around with a couple of things.

• it appends a header to the outgoing request that effectively disables any compression
• it monkey patches the stream methods such that it can buffer the response body in memory
• once the response is fully buffered, string replacements are performed

Outgoing requests get transformed like this:

GET localhost:3000/index.html
Accept-Encoding: gzip, deflate, br, zstd

# becomes...

GET https://example.com/index.html
Accept-Encoding: identity

and incoming responses have the equivalent of this applied (of course, it's not exactly this, but you see the point):

const buffered_body = await req.get("example.com");
const altered_html = buffered_body.replaceAll("example.com", "localhost:3000");
res.write(altered_html)

It's a really cool feature, because you can combine it with local static assets, optionally overriding individual requests. Imagine a remotely hosted Wordpress site, and you just want to tinker with the CSS without having to set up an entire environment? Those are the kinds of weird and wonderful workflows that our community use Browsersync for 😍

Was it fast though?

Part of the reason for sending Accept-Encoding: identity in the outgoing request, is to force the 3rd party to not send a gzip/brottli response. It makes the body a bit larger, but it means that we don't need to do the decompression on the node layer, so in theory the proxy method should be fairly fast.

In real world scenarios though, we see that the proxy introduces a noticeable slowdown.

We can use the Browsersync homepage as a nice, simple example, because it's served from Netlify's CDNs and the response bodies are all encoding with brottli.

If we run the following command, we can take a look at some simple metrics

browser-sync https//browsersync.io

Now we can access localhost:3000 and all requests will be forwarded onto https//browsersync.io, but with the modifications mentioned above.

The page weight is much larger since we're opting out of compression for the reasons mentioned above, but it's striking to me just how much slower the overall page load time is. 😭

Enter the Rust-Rewrite

Even though it's still an ongoing effort, I have the Rust implementation far enough along now to be able to make initial comparisons. The short version is that the new Rust based proxy introduces no noticeable overhead, whilst also supporting compression on both ends of the proxy 💪

So the rust version is much, much faster and is easier to apply compression/decompression where needed.

This is just the tip of the iceberg though, since the composition model in the axum and tower ecosystem is so strong that it doesn't require the monkey-patching of any request/response stream writers like it does in node 😍

Looking forward

Although it's fun to jump on the 're-write it Rust' bandwagon, there are some other reasons improving the proxy element of Browsersync is so important.

If you have a close-to-zero-cost local development proxy, then you can start applying more modifications to the requests/responses without the fear that it's going to grind to a halt.

Some of the recent examples I've been playing with whilst developing the proxy is recording and then playing back streaming responses from LLM providers 👌 💻

After spotting an 18mb binary lurking in the node_modules folder of a project I'd released with napi-rs, I was curious about how much I could reduce it.

I was convinced of two things:

• First, that I'd only be able to trim a megabyte here or there with a combo of various release options.
• Second, that any larger wins would come from considering which 3rd-party crates I'm using and swapping them out for lighter weight ones.

In the end, I was so wrong on the first part, that I thought it was worth sharing in this post. If I end up tweaking 3rd party dependencies to further reduce binary size, I'll be sure to document that process too.

Journey

I was reading this post Trimming down a rust binary in half , but it seemed like swapping out dependencies was a much bigger task than I wanted to take on right now. The post eventually links out to min-sized-rust though—so I started copy/pasting options from there seeing where it led me 🤣.

Impact

Well, with zero changes to dependencies, I cut 11mb from the binary size! I've documented each option I added and what difference it made to the output size 🤌

In each case, I'm just adding another line within the [profile.release] section of Cargo.toml, and re-running this:

cargo build --release

Note: If you're using napi-rs, these same optimizations will apply when you run the relevant build command ✅

Result - 11mb smaller overall!

Now, when I publish my program to npm, users are only downloading a 7mb binary, compared to an 18mb one 🎉. Of course, I can further shrink this—I'm not exactly happy with it being 7mb, but I did find it interesting that with zero code/dependency changes I was still able to shrink the size so much!

Note: In my use-case, I'm optimizing for size over performance (with opt-level = "z") since I'm building a development server where raw-performance is not the primary concern

Copy/Paste

[profile.release]
strip = true
opt-level = "z"
lto = true
codegen-units = 1
panic = "abort"

Legend: Explanation of Cargo Options (this part is from ChatGPT)

I saw this pattern recently, taking advantage of the fact that Typescript doesn't mind if you re-use the same name for a value and a type.

import * as z from "zod"

// Define a schema
export const User = z.object({
    name: z.string()
})

// export an inferred type for use elsewhere
// but, using the same name, `User` 🤯
export type User = z.infer<typeof User>

So we have...

• export const User ...
• export type User...

... it might seem odd, but Typescript is more than happy with this - after all, types and values are distinct! So, providing that you're happy with any potential confusion in the future , it's a pattern you can use right away!

Why would you though? Well, it might make more sense in the context of a consumer - consider the following in a separate module:

import { User } from "./zod"

function signIn(user: User) {
    console.log(user);
}

Here we have a single import: User. We know the module exports both a type and a value with that name - but when seen in type parameter position like this, Typescript will just use the type User without issue. A naming 'collision' just doesn't occur.

In that very same file, we could also do:

// same file, different context
const parsed = User.safeParse({ name: "Shane" })

which is nice - because now we're just in regular JavaScript territory here, using the value called User. Typescript understands that we're not in a type position, so everything 'just works' and we didn't need to think of a separate name for it, like UserSchema or similar. 🥰

JSDoc

All of the examples above were in Typescript - but if you're using JSDoc this works almost identically.

First, instead of exporting both of these...

• export const User ...
• export type User ...

we'll need to replace the second one - since export type ... is only supported in Typescript.

To do this, albeit in a less-than-ideal way, we can use a @typedef

import * as z from "zod"

export const User = z.object({
    name: z.string()
})

/**
 * @typedef {import("zod").infer<typeof User>} User
 */

Using infer from Zod, we're achieving the exact same inference as we did in Typescript - it's just that it's inside a comment this time instead!🥹.

@typedef isn't ideal for all situations (for another time...), but in this case it has exactly the effect we're looking for.

Considering a consumer in JS, as we did with the Typescript example, it would look like this:

import { User } from "./jsdoc-zod";

/**
 * @param {User} user
 */
function signIn(user) {
    console.log(user);
}

Again, note we're only importing User - which is both a type and a value in the other module. Typescript still has no issue understanding that within a @param block, we are referring to the type and not the value.

That means the previous "in the same file" example works just as it did before, presented here as a single snippet:

import { User } from "./jsdoc-zod";

/**
 * @param {User} user - works as expected in type position 🥰
 */
function signIn(user) {
    console.log(user);
}

// works as expected as a value too 🥰
const parsed = User.safeParse({ name: "shane" })

Conclusion

It's becoming table-stakes for any schema parsing library like Zod to support rich type inference. Having types derived from runtime validation code is a powerful pattern, one that I can see growing in popularity.

This post highlights how you can use a single name for a value and a type - and how it can be done in JSDoc along with Typescript.

import { type Metadata } from 'next'

import { Providers } from '@/app/providers'
import { Layout } from '@/components/Layout'

import '@/styles/tailwind.css'

export const metadata: Metadata = {
  title: {
    template: '%s - Shane Osbourne',
    default:
      'Shane Osbourne - Software designer, founder, and amateur astronaut',
  },
  description: 'I’m Shane, a software engineer from Nottinghamshire, England',
  alternates: {
    types: {
      'application/rss+xml': `${process.env.NEXT_PUBLIC_SITE_URL}/feed.xml`,
    },
  },
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en" className="h-full antialiased" suppressHydrationWarning>
      <body className="flex h-full bg-zinc-50 dark:bg-black">
        <Providers>
          <div className="flex w-full">
            <Layout>{children}</Layout>
          </div>
        </Providers>
      </body>
    </html>
  )
}

fn measure_cargo_toml() -> usize {
    let toml = std::fs::read_to_string("Cargo.toml")?;
    toml.len()
}

Putting whether this is an optimal way to read a file's length to one side for a moment, let's take a look into why this causes a compile-time error.

std::fs::read_to_string("Cargo.toml") returns Result<String, std::io::Error> and we tried to use the question mark operator ? to 'unwrap' the String part that we really care about.

We're faced with the following error however:

cannot use the `?` operator in a function that returns `()`
this function should return `Result` or `Option` to accept `?`

This is suggesting that the ? is doing a bit more than simply 'unwrapping' a value - why's it mentioning the return type at all?

To understand, let's try to unwrap that String value a couple of other ways...

if let patterns

If we only ever cared about the success case, then technically we could have done the following instead:

fn measure_cargo_toml() -> usize {
    if let Ok(toml) = std::fs::read_to_string("Cargo.toml") {
        toml.len()
    } else {
        0
    }
}

Notes:

• (line 2): we're performing a pattern-match on the return value from read_to_string here. The code within the if block will only execute if the pattern Ok(toml) is a match against the result.
• (line 5) It looks like our design is breaking down here. To keep the type checker happy we're having to use a 'default' value of 0 when the file reading fails. This is far from ideal since 0 could actually be a valid value, but more so because it doesn't correctly encode what our function is capable of.

Rust can help us here though, we can use the type system to encode more meaning into our function signatures - in this case the presence vs absence of a value can be communicated through the use of the Option enum.

If we change our return type to Option<usize>, then we can return a None in place of the 0 and callers of this function will have a better understanding about how this works.

fn measure_cargo_toml() -> Option<usize> {
    if let Ok(toml) = std::fs::read_to_string("Cargo.toml") {
        Some(toml.len())
    } else {
        None
    }
}

Notes:

• (line 1) we changed the return type from usize to Option<usize>
• (line 3) because of that, we now need to wrap our return value in the Some variant
• (line 5) None here makes our program more explicit than the previous 'default' value of 0

That's a lot of boilerplate though...

Converting from Result<T, _> to an Option<T> is a fairly a common operation, and the standard library comes with a .ok() method to help us reduce a bit of boilerplate:

pub fn measure_cargo_toml() -> Option<usize> {
    std::fs::read_to_string("Cargo.toml") // Result<String, io::Error>
        .ok()                             // Option<String>
        .map(|toml| toml.len())           // Option<usize>
}

Notes:

• Calling .ok() gives us Option<String> or None depending on whether read_to_string was successful - it's just a convenience method and allows us to call .map() to change the inner value, if it exists.

This is a pretty slick example, it's one of the reasons I enjoy Rust so much 🦀

But wait a minute - that's ignoring any errors that might occur when reading the file - what if we wanted to handle that error by passing it on to callers, or even just logging out the error?

To do this, we need to think about our design again. Currently, our signature is this:

pub fn measure_cargo_toml() -> Option<usize> {
    // snip
}

We can produce a usize value, or not - that's it. Our design doesn't incorporate error handling at all. So let's change that.

We can alter our return type to be the following instead:

-pub fn measure_cargo_toml() -> Option<usize> {
+pub fn measure_cargo_toml() -> Result<usize, std::io::Error> {
    // snip
}

With this change, callers of our function will now be forced to handle the fact that our function can fail. They may decide (as we did before) to ignore the error and use a default value, but at least this design gives them that choice. Option<usize> loses all information if something goes wrong, and we don't want that.

So, to update our implementation to forward any errors, we can do the following instead:

The re-wrapping method

pub fn measure_cargo_toml() -> Result<usize, std::io::Error> {
    match std::fs::read_to_string("Cargo.toml") {
        Ok(toml) => Ok(toml.len()),
        Err(err) => Err(err)
    }
}

• When we match on the Ok variant, we get a local binding to the value contained inside, named toml here, then because our return type is also a Result, we need to Ok-wrap the value we get from calling toml.len()

• For the error case we're just re-wrapping the error since it matches our type std::io::Error

That's quite a bit of syntax and ceremony for what is essentially a 'change the value inside the box' operation though - but fear not, Rust has yet more convenience methods to help with situations like this.

The .map() method on Result

We previously saw .map being used to alter the value inside a Option - well it turns out that we can perform the same type of operation on Result too.

pub fn measure_cargo_toml() -> Result<usize, std::io::Error> {
    let result = std::fs::read_to_string("Cargo.toml");
    result.map(|s| s.len())
}

• read_to_string returns Result<String, std::io::Error> - that's very close to what we want. The error part matches our signature, but the value part does not.
• To change just the value then, without explicitly unwrapping it, we can use the .map method as seen here. This will only execute the closure on the value type if the result is of the Ok variant. It's like opening a box, checking that everything inside is ok, then replacing the value and closing the box again.

So that's a couple of techniques that we can use to handle possible errors and read and return different values where there are none.

Understanding use cases for the ? operator

So far though, our implementations have only contained 2 operations

• read a file from disk into a string
• return the amount of bytes that make up that string.

Because of this, we've been able to write a couple of different solutions that didn't require much more than 'reaching into a box' to change a value.

However, there are situations where this 'unwrapping' and 're-wrapping' of values is either tedious or just completely overkill for the task at hand.

For example, if we changed our requirement to instead return the combined length from Cargo.toml + Cargo.lock, then we might end up with a solution such as:

pub fn main() -> Result<usize, std::io::Error> {
    let toml = read_to_string("Cargo.toml");
    let lock = read_to_string("Cargo.lock");
    let mut count = 0;
    match toml {
        Ok(str) => count += str.len(),
        Err(e) => return Err(e)
    }
    match lock {
        Ok(str) => count += str.len(),
        Err(e) => return Err(e)
    }
    Ok(count)
}

• Notice how we need to check each result independently so that we can return early if either operation fails. We don't want to continue reading the second file if the first one has produced an error!

We can of course remove some of that duplication too using a for in loop:

pub fn main() -> Result<usize, std::io::Error> {
    let toml = read_to_string("Cargo.toml");
    let lock = read_to_string("Cargo.lock");
    let mut count = 0;
    for result in [toml, lock] {
        match result {
            Ok(str) => count += str.len(),
            Err(e) => return Err(e)
        }
    }
    Ok(count)
}

• This is the key part, - we're still returning early with an error should one occur.

Or, if you prefer a more functional approach, we can remove the loop and mutable variables with try_fold:

pub fn main() -> Result<usize, std::io::Error> {
    let paths = ["Cargo.toml", "Cargo.lock"];
    paths
        .iter()
        .map(|path| std::fs::read_to_string(path))
        .try_fold(0, |acc, item| {
            match item {
                Ok(string) => Ok(acc + string.len()),
                Err(e) => Err(e)
            }
        })
}

• try_fold allows us to reduce a collection down to a single value, but with the added advantage of supporting early returns. It works by continuing to call this closure every time the previous iteration returns an Ok.
• For us that means that line 9 would forward any errors coming from read_to_string - causing the try_fold to stop iterating and return the error. That error it returns matches our function signature, so we can keep everything in a nice neat package with no external variables to mutate.

We can go one step further here too - notice that inside the try_fold closure we're doing the re-wrapping technique mentioned before. Well since we're forwarding any error as-is we can simplify this down to another .map call.

pub fn main() -> Result<usize, std::io::Error> {
    let paths = ["Cargo.toml", "Cargo.lock"];
    paths
        .iter()
        .map(|path| std::fs::read_to_string(path))
        .try_fold(0, |acc, item| {
            item.map(|string| acc + string.len())
        })
}

• Here the type of item is Result<String, io::Error>, so if there's an error the closure given to .map will not be executed - the error will be forwarded instead. That will cause the try_fold to exit early which in turn will cause our outer function to also return.

But...

Back to basics for a second: in the examples above, we've taken the requirement of "read 2 files from disk and sum their byte lengths" and we've ended up with a generic solution that can work with any amount of files.

Whether we choose a for x in xs loop, or a chain of iterator methods, we've still leap-frogged from simple -> complex in a heartbeat - is there any middle-ground to explore?

Enter ?

The core issue we're having here is the ergonomics around reaching into a Result type. Because read_from_string forces us to deal with the fact that it can fail, it means we can't just access the values safely without a bit of syntax ceremony...

... but that's exactly what ? (the question mark operator) is here to solve.

If we laser-focus in on just solving the 2-file problem, our solution could be as simple as:

use std::fs::read_to_string;

fn measure_cargo_files() -> Result<usize, std::io::Error> {
    let toml = read_to_string("Cargo.toml")?;
    let lock = read_to_string("Cargo.lock")?;
    Ok(toml.len() + lock.len())
}

• notice how on both of these lines, we add a ? directly after the read_to_string() call. This will 'unwrap' the value (if it was successful). So the toml and lock bindings here are both of type String - they have been 'unwrapped'. If any of those file-reads were to fail though, we'd return early with the error. 👌

How it works: The error types line up!

This may seem like magic, but it's really just a case of our function signature having a return type that's suitable for all places where we've used ?.

So, our return type is:

Result<usize, std::io::Error>

whilst the return type of read_to_string() is

Result<String, std::io::Error>

The types of the values actually differ - Our return type has usize for the Ok case whereas read_to_string has String. But for the ? operator to work it's only the Err part that needs to line up - and those do! 😎

The Rust compiler will analyze all uses of ? within a function body and determine if each of them is suitable for a possible 'early return' in your function.

A de-sugared version of ? might look something like this:

use std::fs::read_to_string;

fn measure_cargo_files() -> Result<usize, std::io::Error> {
    let toml = match read_to_string("Cargo.toml") {
        Ok(toml) => toml,
        Err(err) => return Err(err)
    };
    // snip
}

• yep! the ? is just de-sugaring to an early-return like this, not so magical after all!

So that's it. The ? operator can be thought of as unwrap or return early -> with the return early bit being the most important part here. Every time you try to use ? you absolutely must consider the context of what an early return would mean.

That can differ greatly based on where you're using ? - something we'll cover in more detail in part 2.

Part 2...

This first post was just a primer to get you thinking of what using ? really means and why it's useful. It's fundamental Rust 🦀 knowledge that you need to have so that we can discuss the many, many more use cases in depth in part 2.

In part 2, we'll cover:

• using ? in async blocks
• using ? in closures
• how ? causes err.into() to be called - allowing automatic conversion between error types

See you then 👋

document.querySelector('[name=room]')?.addEventListener('change', (e) => {
  invariant(e.target instanceof HTMLSelectElement)
  service.send({ type: 'room.join', id: e.target.value })
})