Marvin Hagemeister

Signals vs Query-Based Compilers

2026-01-04T00:00:00Z

Over the winter holidays curiosity got the better of me and I spent a lot of time reading up on how modern compilers achieve interactivity in the days of LSPs and tight editor integrations. And it turns out that modern compilers are built around the same concept as Signals in UI rendering, with some interesting different design choices.

Old Days: The Pipeline Architecture

The classic teachings about compilers present them as a linear sequence of phases that code runs through until you end up with the final binary. Writing a compiler this way is pretty straight forward, assuming that the language is reasonably simple (JavaScript is ridiculously complex and the opposite of simple).

Source Text -> AST -> IR -> Assembly -> Linker -> Binary

First, source code is transformed into an Abstract Syntax Tree (=AST) which transforms the input text into structured objects/structs. It's the place where syntax errors, grammar errors and those kinds of things are caught.

For example: This JavaScript source code...

const a = 42;

...is transformed into something similar to this AST:

{
	"type": "VariableDeclaration",
	"kind": "const",
	"declarations": [
		{
			"type": "VariableDeclarator",
			"id": {
				"type": "Identifier",
				"name": "a"
			},
			"init": {
				"type": "NumericLiteral",
				"value": 42
			}
		}
	]
}

The AST is then pushed through a few more steps until we end up with the final binary.

The actual details of these steps are not important for this blog post and what we described here is very oversimplified. But it's important to know that compilers typically run code through a bunch of different stages until code can be executed. Doing all of this takes time. Too much time to run on every key stroke.

Modern: Query Based Compilers

When a developer changes a single file by typing a single letter, there is a lot of work going on behind the scenes. Ideally, you want to do as little work as possible. Sure, you could add caches to every stage and try to come up with a good heuristic of when to invalidate them, but it becomes difficult to maintain pretty quickly. That's not good.

The key shift in compilers is to not think of them as just a pipeline of transformations, but as a thing you can run queries on. When a user is typing in their editor the LSP asks the editor what are the suggestions at this specific cursor position in this file? When you click "Go to Definition" on an identifier you're asking the compiler to return the jump target (if any).

Essentially, questions are a bunch of queries that you run against your compiler and the compiler should only focus on answering these as quickly as possible and ignore the rest.

This mental shift is what makes modern compilers much more interactive. But how do they do that under the hood and what has this to do with signals?

Queries, Inputs and the Database

Query-based compilers have three key building blocks: Queries, Inputs and a "Database". The core idea is that everything, literally everything, is composed out of queries and inputs. Nothing runs out of the box unless a query is executed.

There is one big query at the top that says "Give me the final binary", this query then fires off multiple other queries like "Give me the IR", "Give me the AST", etc. It's all queries all the way down.

But there are also additional queries like: "What's the type of the identifier in file X at cursor position Y". Such a query fires then another query that triggers the current file to be parsed into AST. With that you can fire another query that gets you the identifier at the cursor position. With that we can then fire off another query that resolves the identifier to its definition. If that turns out to be in another, we ask for that file to be parsed, etc.

The beauty of this architecture is that you don't spend time processing completely unrelated files. You only process what is necessary to respond to a particular query. If a source file is completely unrelated to the running query it will never be processed.

Caches, caches and more caches

To speed things up even further, queries can easily be cached because they are expected to be pure. They should not have any side effects. This means that you can always re-execute a query and get back the exact same result. This property makes it perfect for caching too.

Queries can be automatically cached and when the cache consumes too much memory, you can just clear it. The next invocation of the query will see that there is no cache entry anymore and will simply re-run its logic and cache the results again. It might just run a little slower once until the result is cached again. But will never return an incorrect result.

But for the cache to be correct there is one crucial detail: It also needs to include the passed arg in the hashed cache key. This in turn means when Query A is called in many places with multiple different arguments passed to it, each argument will create a new instance of that query with its own cached return value.

Shape of a Query

A query is typically defined as function with two arguments

Database
Argument (sometimes confusingly also referred to as input)

Expressed in TypeScript it would look like this:

type Query<T, R> = (db: Database, arg: T) => R;

The db parameter is where all queries live on and The arg parameter is what you call the query with. To call a query inside a query you do db.call_other_query(someArg). To make this nicer and the database less of a thing to know about, most implementations add some sugar in the form of macros or decorators:

class MyDatabase extends Database {
	@query
	getTypeAtCursor(file: string, offset: number): Type {
		const id = this.getIdentifierAtCursor(file, offset);
		const type = this.getTypeFromId(id);
		return type;
	}
}

Inputs: The source of truth

When a file changes on disk you want to somehow tell the compiler that it should invalidate it so that the cache entry is cleared and the next time a query asks for it, it re-processes that file. This is done through Inputs. An Input is a stateful object that can be written to. Usually they live on the database too.

watch(directory, ev => {
	if (ev.type === "change") {
		const content = readTextFile(ev.path);
		db.updateFile(name, content);
	}
});

Reading inputs in queries usually involves calling a method or accessing a special property on it.

class MyDatabase extends Database {
  files = new Map<string, FileInput>()

  // Setter helper
  updateFile(name: string, content: string) {
    const input = this.files.get(name) ?? new Input<string>()
    input.write(content)
    this.files.set(name, input)
  }

	@query
	parseFile(file: string): AST | null {
    const fileInput = this.files.get(file)
    if (fileInput === null) return null;

    // Read input
    const code = fileInput.read()

    return parse(code)
	}
}

To change or not to change

The key difference here compared to signals is that nothing really happens we have written to an input. Queries are not automatically re-executed or anything like that. Contrary to Signals in UI programming which are typically some form of "live" subscriptions, Queries are not live.

In a Signals system a change to a source signal marks it as dirty, and then it follows all active subscriptions and flags every derived/computed signal as dirty until it reaches the place where the subscription was triggered. The triggering part is typically called an Effect. Changes are sort of pushed through the system and when it reaches an effect, it re-runs and "pulls" the new values. There are of course various optimization strategies that libraries employ, but that's out of scope for this article. What's important to remember is that they are essentially a push-pull system when it comes to writes.

A push-pull architecture is perfect for UI rendering. Changes often need to be displayed instantly and you need to ensure that the whole screen is in sync. All signals rendered must always show the value of the same revision they were part of. The situation that the top half of the screen shows new values, whereas the bottom half still renders stale ones, should never occur. This is often referred to as a "glitch". Pushing changes through the system is an elegant way to ensure that this never happens. It basically trades more memory with faster execution and being able to guarantee a glitch-free result.

Query based compilers work differently, they are demand driven. You have to ask for them to be re-executed. It's not as crucial that everything happens in the same tick. It's totally okay for the query for autosuggestions to return and the query for type errors to return a few milliseconds later. There is no need to keep some sort of screen in sync per frame. Correctness must be ensured, of course. But the timing guarantees are a bit more relaxed.

Always pushing changes through the system is too expensive because a query based compiler will easily have >100k nodes depending on the project size. At that scale, memory becomes a real performance concern. To reduce the memory consumption, dependencies are only tracked in one direction in a query based system compared to tracking both directions with signals.

The secret sauce: Revisions

But still, like with Signals, correctness is a hard requirement for query based systems. So if queries finish at different times, how is it guaranteed that the results are always correct? The key insight is that ultimately queries are a pure function over their inputs. Given the same inputs, the same result must occur. The result is therefore correct.

Inside the system there is a global revision counter that is incremented with each changed input. Each node has a changed_at and verified_at field that can be used to check the status of the cached value.

interface Node<T> {
	changed_at: Revision;
	verified_at: Revision;
	value: T;
	dependencies: Node<any>[];
}

This tells us whether we can re-use the cached results of a node or not. That said, due to only tracking dependencies in one direction we need to always dirty check all dependencies of a query up to the leaf nodes, unless verified_at is equal to the current revision which allows us to bail out early. When you reach a leaf node and realise that it hasn't changed at all, despite the global revision counter being increased, you just set all verified_at properties of parent nodes to the current global revision. If the input or a query result has changed you update both the changed_at and verified_at fields. But when somewhere a query still returns the same result despite its dependencies having changed, we also bail out and only update only verified_at pointers while unwinding the stack.

What about threading?

This is one killer feature of query based systems. Depending on the programming language to compile, you can aggressively parallelize tasks like parsing files. If you guarantee that each query can only be executed by one thread at a time you can parallelize a lot of work. Since queries tend to be pretty granular you can often kill a thread and spawn it again with the latest revision. This is an aspect that I need to dive into deeper myself, but I find it interesting that restarting work is a possibility at all in such a system.

Which one is better?

It depends. Signals are better for UI rendering, but the query-based system is more appropriate for a compiler. It all depends on the use case. In either way I find it interesting that different systems sorta arrived at similar building blocks and concepts behind the scenes to achieve an incremental system.

I'm kinda wondering what our JavaScript tools would look like if they were built from the ground up to be incremental. What would something like vite look like if it was built as a query-based system? In spirit, a dev server is similar in that it is a living thing that we constantly query for data apart from HMR updates which are pushed from the server. Maybe a mix of both signals and a query architecture would be the golden ticket?

Building From First Principles

2025-10-28T00:00:00Z

It's funny, sometimes I feel like I'm living in two different programming worlds. There is the online world on Bluesky threads, GitHub, blog posts or other platforms where discussions are often dominated by the latest frameworks, the hottest libraries or discussion that feel very abstract. Then there is the other world I live in, the one I share with my local developer friends. And honestly? They're miles apart.

Online !== Offline

In the online realm, the idea of building anything substantial without any of the major frameworks is typically met with bewilderment, if not scorn. "Vanilla JS for an entire UI? Are you mad?" Building something with vanillajs and stringing a few libraries together as needed is immediately labelled as unmaintainable.

But when I meet up with my developer friends the tech stack they use is the most boring one imagineable. Heck, when you ask them about that, they typically just shrug their shoulders. They couldn't care less. We're not talking about some simple demo app either. The apps they are working on are pretty involved from what they do. They are mission critical apps that have real users and solve a concrete business impact. And boy do they work! These are some of the most robust apps I've ever seen.

Intentionally choosing boring tech

The funny bit: Despite not using any frameworks they are one of the most maintainable apps I've had the pleasure to see the code of. They've been able to bang out features much quicker than anyone else I know. We often ping pong some ideas around and the prototype typically follows a few hours later. In my career so far I had the luck to be able to work among such folks. This wasn't an isolated incident project either. What makes them different?

The one thing they have all in common is that they approach anything they do from first principles. Their first thought isn't "Which framework should I use?" It's: "What is the actual problem we're trying to solve?" They think deeply about outcomes, about user experience and the simplest most direct path towards that goal. Technology is merely a means to an end, not the end in itself.

Clarity is key

Their code pretty much reflects this philosophy: Plain, boring and concise with no fluff. You can easily read it top to bottom without needing to jump around to get the bigger picture. There is very little noise there. There is this pragmatic minimalism to it. You won't find layers of abstractions for abstraction's sake. The biggest "debate" - if you could even call it that - usually revolves around how to structure data or where to put side effects.

Does this mean frameworks are bad? No, far from it! The online tech discourse just tends to create a sense of inevitability around particular tools or methodologies. It's my offline peers that remind me that a lot of effective software development exists outside of online framework debates.

The missing link in JavaScript tools

2025-09-11T00:00:00Z

Lately, my mind has been occupied with finding ways to make tools simpler to work with. Our tools of today present a pretty fractured architecture. The frontend layer has to deal with many languages at once, ranging from custom templating languages, importing CSS to JSX or plain JavaScript. Each tool, the linter, formatter, type checker, test runner and dev server typically demands its own unique plugin system and preprocessing logic to help it understand those workflows.

The template predicament

This makes it difficult to innovate frameworks and integrate them with today's tooling. Take .svelte files as an example. How do we teach our linter to understand them? What about type checking? Everything needs its own plugin. But why?

All of these plugins have in common that they get an input string and turn it back into valid JavaScript. To get type checking in Svelte, Vue or other custom languages to work, the code is transpiled in a way that TypeScript understands. The templating bits are converted to JSX and the rest to standard JS. Both JS and JSX can be type checked by TypeScript. When a type checking error is encountered we check the source maps, if it maps back to user code. If it does, report it, else ignore it.

<script lang="ts">
	export let name: string;
	let count: number = 0;

	function handleClick() {
		count += 1;
	}
</script>

<div>
	<h1>Hello, {name}!</h1>
	<p>You have clicked {count} times.</p>
	<button on:click="{handleClick}">Click me</button>
</div>

<style>
	div {
		border: 1px solid blue;
		padding: 10px;
	}
</style>

Pseudo example of what gets sent to the LSP (real world is different, but it's the same idea):

import { SvelteComponent, init, safe_not_equal } from "svelte/internal";

const __svelte_script = (() => {
	let name: string;
	let count: number = 0;

	function handleClick() {
		count += 1;
	}

	return {
		props: { name },
		data: { count },
		methods: { handleClick },
	};
})();

function render() {
	const { name, count, handleClick } = __svelte_script;

	return (
		<div>
			<h1>Hello, {name}!</h1>
			<p>You have clicked {count} times.</p>
			<button onClick={handleClick}>Click me</button>
		</div>
	);
}

TypeScript can perfectly type check this.

A Virtual File System as the Unifying Layer

Imagine a world where we could modify files before handing them off to the type checker or our linter. Something like a virtual file system of some sorts that everyone could tap into. Runtimes could even use this to run your code directly. You could run your code as if it would be any other script:

deno foo.svelte
node foo.svelte

At its heart, this virtual file system is a shared processing pipeline that has quite a lot in common with typical bundler APIs. Because if you think about it, resolveId() and load() + transform() neatly map to file system operations.

Bundler API	File System API
`resolveId`	follow symlink
`load (+ transform)`	readFile

The resolveId function would be reinterpreted as resolving symlinks within this virtual file system. This allows for dynamic mapping and aliasing of files. Similarly, the load and transform phases, where code is read and modified, can be thought of as a readFile call.

Cross-Language usage

Lots of tools are in the process of moving some of their pieces to Rust or other languages like GO. We're now in a situation where we need to account for multiple consuming languages. All of that could be solved by talking to the same processing pipeline via IPC.

Conclusion

I'm not sure when or even if such a thing will ever see the light of day. I would welcome it though, because it would make experimenting with new templating languages or other DSL's in the JS ecosystem much easier. I want to be able to take my pre-processing pipeline with me, regardless of which test runner, linter or formatter I want to use.

Speeding up the JavaScript ecosystem - Semver

2025-08-10T00:00:00Z

Whilst dabbling with the Preact repo I noticed that running npm install takes more than 3s. This seems excessively long and piqued my interest. I was waiting for a good use case to try out cpupro anyway, so this seemed like a perfect fit.

The tar library is kinda expected to be up there as a decent amount of time is spent extracting tarballs. What captured my attention was the semver package though. It's the package that compares all version ranges of all the dependencies in your project to figure out which versions to install. The versioning is based on the semver standard which defines a major, minor, patch and an optional prerelease component:

1.2.3 # major.minor.patch
2.0.0-alpha.3 # major.minor.patch-prerelease

Package managers go beyond that to allow you to specify ranges or constraints. Instead of only allowing exact versions, they allow you to pass something like ^1.0.0 which means: "Allow any minor or patch version bigger than this version. Ranges can also be composed. You'll often find this sort of format when declaring peerDepdendencies: 1.x || 2.x. Npm supports a plethora of ways to express desired version ranges for your dependencies.

1.2.3  # =1.2.3
4.0.0-alpha.4   # =4.0.0-alpha.4
4.0.0-2  # =4.0.0-2

# Partial versions are also possible
1   # =1.0.0
1.2 # =1.2.0

# Ranges
^2.0.0 # >= 2.0.0 && <3.0.0
~2.0.0 # >= 2.0.0 && <2.1.0
1.x || 2.x # >=1.0.0 || >=2.0.0
1.2.3 - 1.4.0 # >=1.2.3 && <=1.4.0

1.x # >=1.0.0

# ...and more

Parse, don't validate

To get some idea how often the npm binary calls into semver, I've cloned the npm repository, ran npm install and wrapped all exports of the semver library with functions that log out which function was called and with what arguments.

Doing an installation in the preact repo calls about 21.2k times in total into the semver. That's way more than I would've expected. Here are some stats of the functions called:

Function	Callcount
`satisfies`	11151
`valid`	4878
`validRange`	4911
`sort`	156
`rcompare`	79
`simplifyRange`	24

Looking at the table we can see that the call count is entirely dominated by validating and checking if version constraints are satisfied. And that makes sense, because that's what a package manager is supposed to do during installation of dependencies. Looking at the raw function call logs we can see a common pattern:

valid [ '^6.0.0', true ]
validRange [ '^6.0.0', true ]
satisfies [ '6.0.0', '^6.0.0', true ]
valid [ '^0.5.0', true ]
validRange [ '^0.5.0', true ]
satisfies [ '0.5.0', '^0.5.0', true ]
valid [ '^7.26.0', true ]
validRange [ '^7.26.0', true ]
satisfies [ '7.26.0', '^7.26.0', true ]
valid [ '^7.25.9', true ]
validRange [ '^7.25.9', true ]
satisfies [ '7.25.9', '^7.25.9', true ]
valid [ '^7.25.9', true ]
validRange [ '^7.25.9', true ]
satisfies [ '7.25.9', '^7.25.9', true ]
valid [ '^7.26.0', true ]
validRange [ '^7.26.0', true ]
satisfies [ '7.26.0', '^7.26.0', true ]

A huge portion of the satisfies calls are preceded by a call to both valid and validRange. This hints at us that these two functions are used to validate the arguments passed to satisfies. Since the source of the npm cli is public we can check the source code for what these functions are doing.

const valid = (version, options) => {
	const v = parse(version, options);
	return v ? v.version : null;
};

const validRange = (range, options) => {
	try {
		// Return '*' instead of '' so that truthiness works.
		// This will throw if it's invalid anyway
		return new Range(range, options).range || "*";
	} catch (er) {
		return null;
	}
};

const satisfies = (version, range, options) => {
	try {
		range = new Range(range, options);
	} catch (er) {
		return false;
	}
	return range.test(version);
};

To validate input correctness, both validator functions parse the input data, allocate the resulting data structure and return back the original input string if it passed the check. When we call the satisfies function, we do the same work that we just threw away again. This is a classic case of doing twice the work necessary due to not following the "Parse, don't validate" rule.

Everytime you're dealing with parsers and you're validating the inputs before doing the parsing you're burning unnecessary CPU cycles. Parsing itself is a form of validation. It's pointless. By getting rid of the duplicate validation we can save about 9.8k function calls.

With us having logged the function calls prior, we have an ideal benchmark case and can measure the timings with and without duplicate validation. For that I'm using the deno bench tool.

benchmark	time/iter (avg)	iter/s	(min … max)	p75	p99	p995
validate + parse	99.9 ms	10.0	( 85.5 ms … 177.3 ms)	91.1 ms	177.3 ms	177.3 ms
parse	28.0 ms	35.7	( 22.8 ms … 73.3 ms)	26.4 ms	73.3 ms	73.3 ms

Removing the duplicate validation gives us a nice speedboost already. It makes the code ~70% faster.

Does slapping a cache in front of things help?

Over time the folks working on the semver library realized this problem and added an LRU cache, which is sorta a special variant of a Map in JavaScript terms that has a limited number of entries. This is done to avoid the Map growing indefinitely in size. And it turns out it's somewhat effective at speeding things up. Logging out whether a cache entry was found or missed reveals that only 523 times out of 26k calls returned a non-cached result. That's pretty good!

If we remove the caching we can get an idea of how much time it saved.

In total, adding the cache saved about 133ms. Which I guess is not nothing, but far from being effective in the grand picture, despite the amount of cache hits.

Scenario	Time
Uncached	`731ms`
Cached	`598ms`

Caches are a bit of a pet peeve of mine. They can be incredibly useful if used sparingly at the right places, but they are notoriously overused across the JavaScript ecosystem. It often feels like a lazy way to increase performance, where instead of making your code fast, you try to cache the results and kinda hope for the best. Making your code fast instead, yields much better results in many cases.

Caches should be seen as the last form of measure to take when all other options have been exhausted.

How fast can we make it?

With semver having a small grammar to parse, I kinda felt nerdsniped to have a go at it myself. Over the course of a day I wrote a semver parser and added support for all the ways npm allows you to specify a semver constraint. The code is doing nothing out of the ordinary. It loops over the input string, detects the relevant tokens and creates the final data structures out of that. Anyone familiar with parsers would've come up with the same code. It's doing nothing special. No secret JavaScript performance tricks or anything.

function parseSemver(input: string): Semver {
	let ctx = { input, i: 0 };
	let major = 0;

	let ch = ctx.input.charCodeAt(ctx.i);
	if (ch >= Char.n0 || ch <= Char.n9) {
		major = parseNumber(ctx);
	} else {
		throw invalidErr(ctx);
	}

	ch = expectDot(ctx);

	let minor = 0;
	if (ch >= Char.n0 || ch <= Char.n9) {
		minor = parseNumber(ctx);
	} else {
		throw invalidErr(ctx);
	}

	// ...and so on
}

And then we need some code that can check if a version satisfies semver constraints, which is structured in a similar way.

With us having logged all function calls prior, we have the ideal dataset for a benchmark. For the first one, although I've kept the validate + parse steps.

benchmark	time/iter (avg)	iter/s	(min … max)	p75	p99	p995
node-semver	99.9 ms	10.0	( 85.5 ms … 177.3 ms)	91.1 ms	177.3 ms	177.3 ms
custom	3.9 ms	255.3	( 3.7 ms … 6.1 ms)	4.0 ms	4.7 ms	6.1 ms

Even with doing the unnecessary validate step, the custom parser is 25x faster. If we capture a CPU profile of the amount of work done, the difference is even more stark.

Let's get rid of the unnecessary validation step for the next benchmark for both of them.

benchmark	time/iter (avg)	iter/s	(min … max)	p75	p99	p995
node-semver	28.0 ms	35.7	( 22.8 ms … 73.3 ms)	26.4 ms	73.3 ms	73.3 ms
custom	2.9 ms	347.2	( 2.7 ms … 6.4 ms)	2.9 ms	3.4 ms	6.4 ms

With a level playing field of not doing unnecessary validation the difference is much smaller, but still in the order of 10x faster. So in summary the semver checks can be made 33x faster than they are now.

Conclusion

As usual, the tools in the JavaScript ecosystem aren't slow because of the language, but because of slow code. At the time of this writing, the semver library is used in all popular package managers. It's used in npm, yarn and pnpm. Making this faster or switching to a faster alternative would speed the installation process up considerably for all of them.

Speeding up the JavaScript ecosystem - Rust and JavaScript Plugins

2025-02-23T00:00:00Z

Over the past year (2024) there has been a strong movement to rewrite JavaScript tools in Rust to make them faster. Rust is well suited for this as it runs much closer to hardware and doesn't rely on garbage collection. This makes it an ideal candidate for computationally intensive tasks. Linting in its basic form is such a task, as it involves parsing and traversing lots of source code.

But there is a big elephant in the room: Plugins.

The Rust plugin dilemma

To me the main reason the JavaScript ecosystem has flourished in the past years is the pluggability of our tools. You want to explore a custom template syntax for your framework? Just write your own babel plugin. You want to extend ESlint with custom rules? Just write a plugin. The list goes on and on.

Rust on the other hand being a different language is less accessible to JavaScript developers. There is a shared concern that by interfacing with JavaScript you'd lose the performance gains achieved with going with Rust in the first place due to the overhead of serializing and deserializing messages between the two languages. And that's for good reason, that part is costly.

For this reason there is a strong desire to stay in Rust-land as much as possible. Some tooling developers even go so far as ditching JavaScript entirely and favouring some form of query language like GritQL as a way to extend their tools. But this in turn creates new problems: No JavaScript developer knows that query language. How do you debug it? How do you test it? etc.

Is there any chance JavaScript plugins can ever be made fast together with Rust?

Serialization and deserialization costs

Solving this exact problem became my main task at the end of 2024. We wanted to add support for JavaScript plugins in Deno's built in linter. The goal was to have a plugin system that is compatible with ESLint, which means the AST format we're going to use is TSESTree which itself is a superset of ESTree with support for TypeScript and JSX.

The first prototype relied on plain JSON as the message format. It's well supported and pretty much every language ships with an optimized JSON parser out of the box. As a test case we picked the checker.ts file in TypeScript's code base. It contains 53036 lines of code and ends up creating 610k AST nodes in total. Enough to stress test the serialization and deserialization aspect.

Task	Time (in s)
`serde-json` + `JSON.parse()`	2.91s

And yeah, as expected, it's slow. However, this gives us a good reference point to compare future optimizations to. Whilst there are various strategies to reduce the serialization overhead by going with a custom format, we need something that's multiple order of magnitudes faster.

What if we could get rid of the deserialization overhead entirely? What if the JavaScript side could traverse the AST tree by walking the received buffer directly without ever having to deserialize it? Instead of creating 610k AST nodes, we would create zero nodes on the JavaScript side.

Flattening the AST

The tricky bit is that ASTs are a tree structure. They're composed of objects pointing to other objects and we somehow need to represent it as a flat list. That flat list needs to be able to be expressed in numbers in a buffer, like a Uint8Array. What's worse is that every node has different amounts of object properties and few have a similar shape.

// Input: if (condition) { foo() }
const ast = {
	type: "IfStatement",
	test: {
		type: "Identifier",
		name: "condition",
	},
	consequent: {
		type: "BlockStatement",
		body: [
			{
				type: "ExpressionStatement",
				expression: {
					type: "CallExpression",
					// ...
				},
			},
		],
	},
	alternate: null,
};

When you flatten a recursive structure, you typically have to either insert start and end markers in your message or pre-calculate offsets to the relevant nodes in your buffer. This is necessary to know when a node begins and ends. It's doable but that bookkeeping overhead quickly becomes annoying to keep track of.

A much more elegant approach to this problem is to store every AST node in an array and leverage the index into that array as the node's id. Instead of having nodes pointing to other nodes directly, you'll point to other nodes via its id.

const ast = [
	// First node at index 0 is a placeholder as we'll use the
	// index 0 as an empty value
	{ type: "" },
	{
		type: "IfStatement",
		test: 2, // Points to index 2
		consequent: 3, // Points to index 3
		alternate: 0, // Empty, points to placeholder node at index 0
	},
	{
		type: "Identifier",
		name: "foo",
	},
	{
		type: "BlockStatement",
		body: [3],
	},
	// ...etc
];

This flattens the tree so that we don't have to deal with the recursiveness anymore. We still need to deal with the variable amount of properties though. Consequently, a way to make every node the same shape is needed.

For our use case of linting the AST tree, we can safely assume that walking the AST tree is the most common operation. We need to visit parent nodes first and then all their children in order. But we don't really care under which property a child node can be found. What matters is that we visit all child nodes in the correct order.

We can exploit that aspect by extracting out all properties into a separate data structure. The nodes itself will only keep the type, a child, next and parent pointer. Theoretically, you could drop the parent pointer, but it's going to make our life easier because linting rules in ESLint can traverse upwards at any time. The node itself only contains information how to traverse it, without any knowledge of its properties.

const ast = {
	properties: [
		{},
		{ test: 2, consequent: 3, alternate: 0 },
		{ name: "foo" },
		{ body: [3] },
	],
	nodes: [
		// First node at index 0 is a placeholder as we'll use the
		// index 0 as an empty value
		{ type: "", child: 0, next: 0, parent: 0 },
		{
			type: "IfStatement",
			child: 2, // Points to index 2
			next: 0,
			parent: 0,
		},
		{
			type: "Identifier",
			child: 0,
			next: 3, // Point to next child of IfStatement
			parent: 1, // Parent node is IfStatement
		},
		{
			type: "BlockStatement",
			child: 3,
			next: 0,
			parent: 1, // Parent node is IfStatement
		},
		// ...etc
	],
};

With the new shape, we can traverse a node and its children by walking the child pointers, followed by iterating over the next pointers. Traversal becomes very simple and can be expressed with very few lines of code.

function traverse(buf, idx) {
	// Check if a lint rule matches
	if (matches(buf, idx)) {
		visit(buf, idx);
	}

	// Traverse over children
	const childIdx = readChild(buf, idx);
	if (childIdx > 0) {
		traverse(buf, childIdx);
	}

	// Traverse next siblings
	const nextIdx = readNext(buf, idx);
	if (nextIdx > 0) {
		traverse(buf, nextIdx);
	}
}

The reason traversal has become so simple is that the node's data structure only ever contains traversable properties like child and next. We never have to check if a property is traversable or not anymore. This seems like a minor detail, but reduces the number of checks you have to do during traversal and typically makes code simpler.

The only part of variable length left is the type property. We can get rid of that variableness by storing strings in a string table and referring to a string by its index into that table instead. This has the neat benefit that it also compresses our message at the same time, because we only ever store a particular string once in our message.

const ast = {
	stringTable: ["", "IfStatement", "Identifier", "BlockStatement"],
	properties: [
		{},
		{ test: 2, consequent: 3, alternate: 0 },
		{ name: "foo" },
		{ body: [3] },
	],
	nodes: [
		// First node at index 0 is a placeholder as we'll use the
		// index 0 as an empty value
		{ type: 0, child: 0, next: 0, parent: 0 },
		{
			type: 1, // StringTable index 1
			child: 2, // Points to index 2
			next: 0,
			parent: 0,
		},
		{
			type: 2, // StringTable index 2
			child: 0,
			next: 3, // Point to next child of IfStatement
			parent: 1, // Parent node is IfStatement
		},
		{
			type: 3, // StringTable index 3
			child: 3,
			next: 0,
			parent: 1, // Parent node is IfStatement
		},
		// ...etc
	],
};

Effectively, our new format allows us to represent a node with just 4 numbers. We can drop the object property names and flatten the data even further by storing all numbers in the same array. Each node has the same length which allows us to easily calculate the offset of each node on the fly. We don't need to keep track of offsets anymore as the offset and the fixed size of a node gives us enough information to know where a node starts and ends.

[
	// Empty placeholder node
	0, // type
	0, // child
	0, // next
	0, // parent

	// IfStatement
	1, // type
	2, // child
	0, // next
	0, // parent

	// Identifier
	2, // type
	0, // child
	3, // next
	1, // parent

	// BlockStatement
	3, // type
	3, // child
	0, // next
	1, // parent
];

To get a node's offset in the buffer, we'll use this simple formula: index * 4. It's as simple as that. Doing this calculation on the fly costs practically nothing.

Lazy deserialization

So far we've only focused on the traversal aspect, but when a lint rule matches we still need to materialize an actual object for the lint rule to consume. We don't want to expose the buffer directly to users and in fact they should be completely unaware of that.

However, we want to be really careful to only materialize nodes that are actually needed. If we'd materialize a node and all its children upfront we'd nullify a huge portion of the optimization work we've put in so far.

A solution to this problem is to go with a facade class that looks like a node, but has a bunch of getters getters that surf over the underlying buffer instead. When you access a getter in a lint rule that points to another node, we'll materialize that one on demand. We will only ever materialize a node the user asked for, never more.

class NodeFacade {
	constructor(buffer, stringTable, propertyTable, index) {
		this.#buffer = buffer;
		this.#stringTable = stringTable;
		this.#propertyTable = propertyTable;
		this.#index = index;
	}

	get type() {
		const typeNum = this.#buffer[this.#index];
		return this.#stringTable[typeNum];
	}

	get test() {
		const properties = this.#propertyTable[this.index];
		const property = properties["test"];
		if (isNodeIndex(property)) {
			return new NodeFacade(
				this.#buffer,
				this.#stringTable,
				this.#propertyTable,
				property
			);
		} else if (isString(property)) {
			// ...
		}
	}

	// ... more getters here
}

Since there are way less than 255 unique properties for all AST nodes (JavaScript + TypeScript + JSX) combined, we can go even one step further and simply create getters for every property upfront (thanks to @jviide for that tip!). This might seem like an odd choice, because not every node has every property, but we can pretend to only have specific properties through typing it differently in TypeScript.

interface Visitor {
	Identifier(node: { type: "Identifier"; name: string }): void;
	IfStatement(node: {
		type: "IfStatment";
		test: Expression;
		consequent: Statement;
		alternate: Statement;
	}): void;
	BlockStatement(node: { type: "BlockStatement"; body: Statement[] }): void;
}

From a typing perspective the lint rule always gets the correct object, but in reality the object is an instance of our NodeFacade class and has many more properties. The genius part here is that our code gets a lot shorter. We don't need to declare 170+ different classes for every AST node type. We just need a single one. We've hidden the fact that we're just surfing over a buffer object behind the scenes completely.

const eslintPlugin = {
	name: "my-plugin",
	rules: {
		"my-rule": {
			create(ctx) {
				return {
					IfStatement(node) {
						// Just an example
						if (node.test.type === "Identifier" && node.test.name === "foo") {
							ctx.report({
								node: node.test,
								message: "Don't pass 'foo' to an IfStatement",
							});
						}
					},
				};
			},
		},
	},
};

With all optimizations in place the number looks much better. Sure, there is still some overhead of running plugins compared to not running them at all, but it's gotten fast enough to be usable at this point.

Task	Time (in s)	Speedup
`serde-json` + `JSON.parse()`	2.91s	-
custom	0.62s	~4.7x

The whole traversal and selector matching code only takes 20.4ms for 610k AST nodes. Most files have much less nodes, like around ~6000 nodes or fewer. Nearly all time is now exclusively consumed by the serialization step. There are some optimizations still left to explore that I haven't gotten around to. But for now it's fast enough.

Here is a quick demo of the lint plugin system in action:

Bonus: Supporting all the languages

With a generic NodeFacade class we now have no aspect in our data format that's tied to the TSESTree or ESTree format anymore. The data format has no knowledge of what it contains. It just knows that it's a bunch of objects with a specific hierarchy encoded in them. It's completely independent of any language. We could pass in a CSS AST tree, a markdown AST tree or any AST from any other language and the plugin system would support it out of the box.

The key thing that enabled us to do that was to encode tree traversal in a generic way in our data format.

Conclusion

So there you have it. Rust can work together with JavaScript plugins in a performant way. I think that this is the future of JavaScript tooling. Keeping pluggability alive is very important to me and I think for the ecosystem at large. All this work described here was done in a span of two months and shipped in Deno 2.2. There is still some work left to do to support ESLint's config format, but you can already run (or write) raw ESLint plugins and have them run with deno lint. Bartek even wired everything through the rest of Deno so that you can apply fixes, and see suggestions from your lint plugins right in your editor.

All in all, I think Rust is here to stay in our JavaScript tools. I'm excited to see where the future leads us and how we can make both Rust and JavaScript work even better together.

The modern way to write JavaScript servers

2025-01-25T00:00:00Z

If you've visited Node's homepage at some point in your life you have probably seen this snippet:

import { createServer } from "node:http";

const server = createServer((req, res) => {
	res.writeHead(200, { "Content-Type": "text/plain" });
	res.end("Hello World!\n");
});

// starts a simple http server locally on port 3000
server.listen(3000, "127.0.0.1", () => {
	console.log("Listening on 127.0.0.1:3000");
});

It shows how to create a plain web server and respond with plain text. This the API Node became famous for and it was kinda revolutionary when it came out. These days this call might be abstracted away behind frameworks, but under the hood, this is what they're all doing.

It's nice, it works and a whole ecosystem has formed around that. However, it's not all roses. A pretty big downside of this API is that you have to bind a socket and actually spawn the server. For production usage this is perfectly fine, but quickly becomes a hassle when it comes to testing or interoperability. Sure, for testing we can abstract away all that boilerplate like supertest does, but even so it cannot circumvent having to bind to an actual socket.

// Example supertest usage
request(app)
	.get("/user")
	.expect(200)
	.end(function (err, res) {
		if (err) throw err;
	});

What if there was a better API that doesn't need to bind to a socket?

Request, Response and Fetch

Enter the modern times with the fetch-API that you might be already familiar with from browsers.

const response = await fetch("https://example.com");
const html = await response.text();

The fetch()-call returns a bog standard JavaScript class instance. But the kicker is that the same is true for the request! So if we zoom out a little this API allows every server to be expressed as a function that takes a Request instance and returns a Response.

type MyApp = (req: Request) => Promise<Response>;

Which in turn means you don't need to bind sockets anymore! You can literally just create a new Request object and call your app with that. Let's see what that looks like. This is our app (I know it's a boring one!):

const myApp = async (req: Request) => {
	return new Response("Hello world!");
};

...and this is how we can test it:

// No fetch testing library needed
const response = await myApp(new Request("http://localhost/"));
const text = await response.text();

expect(text).toEqual("Hello world!");

There are no sockets involved or anything like that. We don't even need an additional library. It's just plain old boring JavaScript. You create an object and pass it to a function. Nothing more, nothing less. So, how much overhead does binding to sockets end up being?

Benchmark	time/iter (avg)	iter/s
Node-API	806.5 µs	1,240
Request/Response-API	3.0 µs	329,300

Well, it turns out quite a bit! This benchmark might make it look like the difference are miniscule, but when let's say have a test suite that runs this server a thousand times the differences become more stark:

Spawn 1000x	time/ms	speedup
Node-API	1.531s	-
Request/Response-API	5.29ms	289x faster

Going from 1.5s to 5.2ms which is practically instant, made it much more enjoyable to work on the tests.

How do I launch my server?

Now, to be fair, so far we haven't launched the server yet. And that's exactly the beauty of this API, because we didn't need to! The exact API depends on the runtime in use, but usually it's nothing more than a few lines. In Deno it looks like this, for example:

Deno.serve(req => new Response("Hello world!"));

What's way more important than this though is that this API shape works across runtimes. Some use the export default fetch syntax, others use a function call, or an event listener API style. Regardless of what the function is named, the underlying API shape for your code stays the same. You have a function which receives a Request instance and you respond with a Response instance.

type CommonAPI = (req: Request) => Response | Promise<Response>;

export default {
	fetch(request: Request) {
		return new Response("hello world");
	},
};

EDIT: A previous iteration of this article mistakenly said that it this way of responding servers was a proper standard by WinterTC. This is not an official standard at the time of this writing. Different runtimes have just arrived at the same conclusion and made it easy to share code across them.

Conclusion

This API works everywhere today! The only exception here is Node and although they're part of WinterTC they haven't shipped this yet. But with a little good ol polyfilling you can teach it the modern ways to build servers. Once Node supports this natively, a bunch of tooling for frameworks will become easier.

They too, tend to try to turn every runtime into Node which is a big task and causes lots of friction.. That's the exact scenario I ran into when writing adapters for frameworks for Deno and prototyping new APIs.

Shoutout to SvelteKit which is one of the modern frameworks that nailed this aspect and made writing an adapter a breeze!

Speeding up the JavaScript ecosystem - Isolated Declarations

2024-07-06T00:00:00Z

Unbeknownst to many, the new isolatedDeclaration feature shipped in TypeScript 5.5 is much more important than you might realize. It just revolutionized how we package and distribute JavaScript code. You don't need to create *.d.ts files manually anymore by invoking the tsc compiler. "Go to source" (the thing when you do ctrl+click or cmd+click on macOS) actually works now and it leads you right to the TypeScript source code instead of a *.d.ts file or some compiled JavaScript code. And on top of it all it makes publishing packages way faster than ever before.

How did it achieve that? Let's take a step back and assess the current situation of packaging JavaScript code in 2024.

Packaging for npm in 2024 is a mess

Honestly, it's a mess. There is no point in sugar-coating it. A buddy of mine wanted to publish his first every library on npm, but was quickly discouraged when he realized how much work and specialized knowledge that entails. You have to care about CommonJS vs ESM, fiddle with a bunch of settings to make *.d.ts files work and the list goes on. In the end, he aborted the mission and instead just copy and pasted files between his projects around. It was much less of a hassle compared to having to deal with all the packaging woes.

Packaging code should be as easy as the act of uploading files. Packaging and sharing code should be so easy that every developer, no matter their experience level, can do it.

Even for experienced developers, creating npm packages that can be used in every environment is quite a challenge. Mark Erikson from the Redux team wrote a blog post spanning multiple pages about his experience of creating npm packages. The thing is that packaging and sharing code among developers should be easy. Developers shouldn't have to read a dozen blog posts and become experts of the inner workings of all these tools to be able to share code. It should just work.

Various CLI tools emerged to help with this situation, but this just adds another friction point. You got tool A which can fix a part of the problem, then you have tool B which only deals with another piece of the problem and so on. Before you know it, you have to stay on top of which tool is the right one to use, up until it will be replaced by yet another tool. It's bad.

So, how do we fix all of this?

Why generating `.d.ts` files takes so much time

At the heart of the problem is an architectural one. We only ever ship build artifacts, the compiled JS and the relevant .d.ts files in a package. Shipping the original TypeScript source files would be much better, but barely any tool in the JS ecosystem works with that. The assumption that nothing inside the node_modules folder needs to be compiled is too widely baked in our tools. Shipping the TypeScript sources instead of .d.ts files would also be a performance regression when working with TypeScript.

Parsing .d.ts files is much quicker as they contain only the bits needed for type checking compared to a normal .ts file. A .d.ts file contains no function bodies, or other stuff, just the type definitions that are needed for consuming a module.

// Input: add.ts
const SOME_NUMBER = 10;
export function quickMath(a: number, b: number) {
	return a + b + SOME_NUMBER;
}

// Output: add.d.ts, contains only the bits needed for type checking
export function quickMath(a: number, b: number): number;

Oftentimes, the return type of a function is not known. It has to be inferred by the TypeScript compiler by walking and checking the whole function body first. Inference is a very costly thing to do in terms of performance, especially for complex functions. Therefore the goal of creating .d.ts files is to get rid of all inference, so that the TypeScript compiler only needs to read these files and do no additional work. Type inference is the main reason creating those .d.ts files takes so long. And because this process takes so long, we try to do as much of it ahead of time, when creating the npm package.

All this changes with isolated declarations.

Entering a new era of packaging

The idea behind isolated declarations is that you make it trivial for tools other than the TypeScript compiler to generate those .d.ts files from TypeScript source code. It does it by requiring explicit return types for exported functions and other things. But don't worry, if a type is complex to reason about, the TypeScript language server comes with a handy feature to infer the missing type for you.

By turning the process into a mere syntax stripping one, the time to create .d.ts is very close to 0s. With a specialized Rust-based parser this happens in the blink of an eye even for gigantic projects as that work can now be parallized. It's so fast that you don't even notice it. Without isolated declarations you always had to invoke the tsc compiler and run a full type checking pass.

Since the cost to generate definition files became next to nothing, it's easily fast enough to do on the fly when needed. We can flip the process of publishing on its head: Instead of dealing with all the hassle of building .d.ts files and publishing them to npm ahead of time, you can just upload your TypeScript source code as is, and the definition files are automatically generated on the fly whenever you install a package. Generation of the .d.ts doesn't occur when publishing a package, it happens when you install a package.

This also changes how you declare the available entries for your package. Previously, with npm you had to reference a couple of build artifacts to make this work.

// package.json
{
	"name": "@my-scope/my-package",
	"version": "1.0.0",
	"type": "module",
	"exports": {
		".": {
			"types": "./dist/types/index.d.ts",
			"import": "./dist/index.js"
		},
		"./foo": {
			"types": "./dist/types/foo.d.ts",
			"import": "./dist/foo.js"
		}
	}
}

With a system based on isolated declarations this is much simpler: Just reference your source files directly.

// jsr.json
{
	"name": "@my-scope/my-package",
	"version": "1.0.0",
	"exports": {
		".": "./src/index.ts",
		"./foo": "./src/foo.ts"
	}
}

Pointing the entries of your package to the actual source files feels much more natural as it frees you from worrying about packaging artifacts.

Using it in production

Now of course, talking about things in theory is all good and well, but how does such a thing feel in production? The core idea behind isolated declarations have been floated around various times in the TypeScript issue tracker, but it took some time and many smart minds to finalize. Here at Deno (disclaimer: I work for Deno) we've been following that process from beginning very closely and starting working on our own rust-based version of that. The system that we've been talking about so far in this post, is exactly how packaging in Deno works since early December 2023. It's been used in production by every Deno user for more than half a year by now.

Things like "go to source" in your editor work out of the box and actually move you to the source code rather than some random definition file.

We realized the usefulness of having such a system and made it work for everyone, not just for Deno users too. You can use it with npm, with yarn, with pnpm or even with bun. The JSR registry does this by implementing the npm protocol for installing packages and simply acts a yet another npm registry when talking with these package managers. From the package manager's point of view it's no different than talking to any other private npm registry that you may be already using in your company.

Since npm clients don't have a system in place for generating definition files on the fly, we generate them for the npm tarballs during the publishing process behind the scenes. Therefore the npm tarball comes with the standard transpiled .js files like you're already used to from other projects. The whole npm ecosystem is based around shipping .js files and changing that would break the it. The takeaway here is not to only publish TypeScript to npm.

But if you do use a runtime that can run TypeScript natively and use a registry that can also distribute the original TypeScript sources, then having isolated declarations is a game changer.

Conclusion

Isolated declarations just changed the game of publishing forever. It made it a near zero cost process to generate definition files, which opens the door for generating definition files on the fly. This greatly simplifies the publishing process to a mere upload of source files, which is much quicker to do. Right now, JSR is the first and only registry to take advantage of that and it can be used with any package manager and in any runtime. In a nutshell, JSR is aimed at everyone who feels like life is too short to deal with all packaging woes and just wants to share code. Try out it out and see for yourself.

Speeding up the JavaScript ecosystem - Server Side JSX

2024-05-15T00:00:00Z

In the realm of web development, the efficiency of server-side rendering HTML plays a crucial role in delivering fast and responsive user experiences. However, a notable challenge arises from the existing JSX transforms that turn JSX into valid JavaScript: They are primarily tailored for browser environments, often generating excessive memory overhead and causing frequent Garbage Collection pauses. This overhead can be nearly eliminated by rethinking how we transform JSX on the server.

Optimizing JSX for the server

When looking at the transpiled output of commonly used JSX transforms, it’s easy to see why it’s causing frequent GC pauses. They typically don’t differentiate between static and dynamic parts of a JSX "block" and allocate many short-lived objects for both an element and their attributes. The amount of objects to be allocated grows very quickly, the more JSX elements you have.

// input
<h1 id="heading">hello world</h1>;

// output: "classic" createElement transform
React.createElement("h1", { id: "heading" }, "hello world");

// output: newer "automatic runtime" transform
import { jsx as _jsx } from "react/runtime";
_jsx("h1", { id: "heading", children: "hello world" });

On the server, neither of those transformation outputs are ideal. They both create many short-lived objects that will be immediately thrown away after rendering. Since the input JSX element is completely static, the optimal solution would be to transform it directly to a plain string which bypasses the need for those temporary objects in the first place.

// input
<h1 id="heading">hello world</h1>;

// output: precompiled HTML string
const html = '<h1 id="heading">hello world</h1>';

Allocating one string is much less taxing on the Garbage Collector than creating and cleaning up a dozen objects, regardless of how big or small those objects might be.

Mixing static and dynamic parts

But not all templates are static and a huge part of rendering involves mixing static and dynamic pieces. We have something for that already built-in in JavaScript: Tagged template literals. They differentiate between static and dynamic inputs already.

// input
<h1 id="heading">My name is {name}</h1>;

// As a tagged template string
jsxTemplate`<h1 id="heading">My name is ${name}</h1>`;

From an implementation point of view, tagged templates share the following function signature, which is perfect for what we want to do:

function jsxTemplate(statics: string[], ...expressions: unknown[]) {
	// ...
}

We can tailor our JSX transform to generate an array of the static parts of each JSX block and pass the dynamic parts as additional arguments.

const template = ['<h1 id="heading">My name is', "</h1>"];

jsxTemplate(template, name);

I’ve benchmarked if it would make a difference between passing all expressions as an array, or using a rest parameter, but couldn’t find any meaningful changes in performance.

Making it secure

A crucial aspect of generating HTML is to ensure that dynamic input is properly escaped and cannot lead to XSS vulnerabilities. This is something we should take care of in our JSX transform automatically. By wrapping every dynamic part with an additional function call that escapes passed content, we can remove those risks entirely.

const template = [
	// ...
];

// The `name` variable is dynamic and we’ll wrap it with
// an escape function automatically
jsxTemplate(template, jsxEscape(name));

The benefit of baking this into the JSX transform is that it requires frameworks to supply an implementation for jsxEscape which reduces the risk of forgetting to escape things properly. Whilst we could leverage the same function for dynamic attribute values as well, most frameworks handle attribute values differently based on which attribute they are dealing with. A common thing during server-side rendering is to drop all event related props like onClick for example.

// input
<h1 class={someVariable}>hello world</h1>;

// output: precompiled
const template = ["<h1 ", ">hello world</h1>"];

jsxTemplate(template, jsxAttr("class", name));

With the jsxAttr function framework authors can decide to drop the whole attribute if desired. Note that they still need to ensure that they’re escaping the attribute value accordingly.

What about components?

Components are a bit of a special case in that it’s entirely up to the framework how they’re implemented and what they do under the hood. If we want to keep our JSX transform usable for any framework, we cannot make assumptions here. For that reason we’ll simply fall back to the automatic runtime transform in this case.

// input
<Foo foo="bar" />;

// output: precompiled, same as automatic runtime transform
jsx(Foo, { foo: "bar" });

How much faster is it in the real world?

Synthetic benchmarks show that a precompiled approoach is around 7-20x faster, but the more interesting question is how it behaves outside of that. Real projects are often very different from synthetic benchmarks. For that reason I picked my own site for this. The code has a healthy mix of static parts and dynamic components. As usual, the numbers are measured on my MacBook M1 Air.

Transform	Time	ops/s	improvement
Classic	40.92 µs/iter	24,439.7	1x
Automatic Runtime	38.32 µs/iter	26,098.1	1.06x
Precompile	5.12 µs/iter	195,312.5	8x

Visualized as a chart:

Conclusion

Interestingly, the core idea presented here is nothing new. In truth, this is how every templating language that outputs HTML has worked since at least the early 2000s (likely even older). However, with the rise of JSX and the popularity of Single-Page-Apps, focus was shifted away from the server to the browser. Since then many framework specific transforms or even full custom file-formats have been invented. There is Svelte, there is Vue and there is Solid which works closest like the strategy described in this post. They also transpile JSX to a stringified output.

The key difference here though is, that the transform isn’t tied to a particular framework. It works like the standard "classic" and "automatic runtime" JSX transforms in that it can be used with any JSX-based framework. Whether you are using Preact, Hono’s JSX layer, or something entirely different or custom grown is not important as you can support the "precompile" transform with minimal effort. Both Preact and Hono’s JSX support it out of the box already.

Enabling the new "precompile" transform in Deno (Disclaimer: I'm employed by Deno) is as easy as changing one line in the config file.

  // deno.json
  {
    "imports": {
      "preact": "npm:preact@^10.22.0",
      "preact-render-to-string": "npm:preact-render-to-string@^6.4.2"
    },
    "compilerOptions": {
-     "jsx": "react-jsx",
+     "jsx": "precompile",
      "jsxImportSource": "preact"
    }
  }

And with that change you can make rendering JSX on the server in your app 7-20x faster and reduce Garbage Collection times by 50%. The more static elements you have the faster the transform can render HTML. The beauty about this transform is that even in the worst case scenario where there is no static content, it will have at least the same performance characteristics as the existing JSX transforms. It will never be slower, it can only be faster.

Speeding up the JavaScript ecosystem - Tailwind CSS

2023-11-01T00:00:00Z

Admittedly, I currently don’t have a bigger project written with Tailwind CSS at hand at the moment. Those that do use Tailwind are too small in scope to make a meaningful performance analysis. So I thought what better way than to profile Tailwind on its very own tailwindcss.com site! Right at the start I ran into a problem though: The project is built with Next.js which makes it very difficult to obtain meaningful traces off. What’s more is that the traces contained too much noise completely unrelated to TailwindCSS.

Instead, I decided to run the Tailwind CLI over the project with the very same config to obtain some performance traces. Running the CLI build takes a total of 3.2s, whereas at runtime 1.4s were spent in Tailwind. The machine the numbers are pulled from is my personal MacBook M1 Air. Looking at the profile we can make out some key areas where time is spent:

As usual in my posts, the x-axis of the flame graph doesn’t show time “when it happened” but rather the accumulated time of each call stack which are merged together here. This makes it a lot easier to see problem areas at a glance. I’m using SpeedScope to visualize the CPU profile.

There is a block that deals with extracting potential candidates for parsing, a block for config and plugin initialization, CSS generation, some PostCSS stuff and when there is PostCSS then autoprefixer typically can be mentioned in the same breath as the two are very frequently used together. It's noticeable that loading autoprefixer without doing anything seems to consume quite a bit of time already.

Switching things up

Going through the Tailwind CSS code base and looking at the profile, there definitely some places where functions could be optimized more. But if we did that we’d only get a couple of single digit percentage improvements. In the previous posts there was typically something obvious jumping out in the profiles, but what do we do here where there is no single obvious indication where time is spent?

The secret to achieving speedups of multiple factors, not just low percentages, is less about applying generic rules or habits like “Don’t create closures inside for-loops”. It’s a common misconception that if you follow all these “best practices” that your code will be fast, because the uncomfortable truth in most instances (read not all) is that it won’t matter much. What makes code truly fast is being aware of what it’s supposed to solve and then taking the shortest path to achieve that goal.

So as a challenge, I thought it would be fun to look at what the architecture of Tailwind’s code would look like, if we built it from scratch with performance in mind. Would we make different decisions? But to be able to find an optimal architecture, we need to know which problem Tailwind solves and think of the shortest path to achieve that.

Little spoiler:

How Tailwind CSS works

At its core, the way Tailwind CSS works is that you pass it some CSS files and it looks for @tailwind rules inside of them. If it encounters such a rule it will crawl the other files in your project to look for tailwind class names and inject it in place in the CSS file where the @tailwind rule was found. There are some more aspects to it, but for sake of simplicity for this article, we’ll ignore the other at-rules for now.

/* Input */
@tailwind base;
@tailwind components;
@tailwind utilities;

.foo {
	color: red;
}

…is transformed to:

.border {
	border-width: 1px;
}
.border-2 {
	border-width: 2px;
}

/* …etc */
.foo {
	color: red;
}

Based on that we can identify several stages in the inner workings of Tailwind CSS:

Scan .css files for @tailwind rules
Find all files to extract tailwind class names from based on glob patterns provided by the user in the tailwind configuration
Once those files have been found, extract potential tailwind class names
Parse potential tailwind class names to check if they are really a tailwind class name. If they are, generate some CSS from that
Replace the @tailwind rule in the original css file with the generated CSS

Optimizing the extraction stage

Since there are only three valid @tailwind rule values, we can bypass the whole PostCSS parsing step by using a basic regex:

/@tailwind\s+(base|components|utilities)(?:;|$)/gm;

With this regex, finding the @tailwind rules and their position in all the CSS files is essentially free, as it takes about 0.02ms. That time hardly matters compared to the full 3.2s time it took for Tailwind CSS. When it comes to finding all files based on user specified glob pattern, there isn’t much we can do that would affect the total time, as we need to reach out to the file system anyways and we’re limited by the readFile function the runtime provides us.

However, once those files are read and we need to extract potential tailwind class name candidates, there is a lot we can do. There is a problem though: How do we detect what is a tailwind class name and what is not? It might sound simple on the surface, but it’s actually not that easy. The problem is that there is no maker or any other indication that a sequence of characters is a valid tailwind class name. There can be combinations of words which have the same format as a tailwind class name, but don’t exist.

Examples of valid tailwind class names:

ml-2
border-b-green-500
dark:text-slate-100
dark:text-slate-100/50
[&:not(:focus-visible)]:focus:outline-none

Is foo-bar a valid tailwind class name? It’s not part of the default tailwind grammar, but it could’ve been added by the user. So the only real option we have here is to reduce the search space as best as we can and then feed our parser with the remaining candidates. If the parser generated some CSS, then we know that the class name was valid. If it didn’t then it wasn’t valid. This in turn means that we need to optimize our parser to bail out as quickly as possible if it detects a string value that it has no definition for.

To remind ourselves: This takes about 388ms in Tailwind CSS currently.

I’ve patched Tailwind CSS locally to reveal some stats about the values the extractor pulls out.

Parsed files: 454
Candidate strings: 26466

But what’s much more interesting is looking at the most common top 10 values that the extraction code pulled out:

- 9774x ''
- 2634x </div>
- 1858x }
- 1692x ```
- 1065x },
-  820x ---
-  694x ```html
-  385x {
-  363x >
-  345x </p>

In other words: Out of the 26466 matched strings, 19630 of them are obviously invalid tailwind class names. Now to be fair, Tailwind CSS has some caching in place to alleviate checking if something is a false positive or not. And there already is a code comment that says that any improvement to their regex could speed up Tailwind CSS by as much as 30%.

Regexing all the things

The blessing and curse at the same time of using regex here is that it isn’t language aware. It doesn’t know if we’re operating on .js or .html files and what’s worse is that languages can be embedded into each other. An .html file can host HTML, JavaScript and CSS at the same time. Same is true for JSX in .jsx files. When it comes to JavaScript code, then we can assume that we only need to look at strings.

A quick and dirty regex later, we reduced the search space from 26466 down to 9633 candidates. Still not optimal, but a lot better than what we started with. A lot of the extracted strings now resemble much more potential tailwind candidates:

relative not-prose [a:not(:first-child)>&]:mt-12
none
break-after
grid-template-rows
...

Each extracted string holds one or more potential candidates. We can reduce the search space further by firing another regex on each extracted string to pull out the parts that could be a valid tailwind class name. Luckily for us, the grammar of a valid tailwind class name follows reasonably simple rules:

No spaces allowed
Variants must end with a colon :
Arbitrary values are defined with wrapping brackets [foo]. They must be located at the end of the class name
A variant can also be arbitrary: [&>.foo]:border-2. Must still not contain spaces
Anything other than the values inside the brackets must only contain numbers, alphabetic characters or the minus sign. I’m not sure if underscore is allowed to, but I guess it could be a user defined tailwind class name
A valid Tailwind class name must start with [, -, !, a-z or 0-9

All this matching does cost some time though and increases the total extraction time to 92ms. And after all our efforts of reducing the search space, we’re still left with around 8000 potential tailwind class names (remember, previously extracted strings could hold multiple candidates).

So far we achieved pretty commendable gains. We reduced the extraction time from Tailwind’s original 388ms down to 98ms. That’s roughly a 4x improvement.

Turning class names into CSS

At this stage we still haven’t generated any CSS rules yet. We still need some rules to replace in favor of the @tailwindcss rules in the original CSS file where we started from. But we are now in a position to do just that with the list of potential tailwind class names. A lot of these are likely false positives so we need to ensure we can bail out as quickly as possible if we detect that a class name doesn’t render CSS.

The first step is parsing the preceding variants if there are any. Remember that variants can be detected by a trailing colon : character. One key aspect of variants is that they only influence the selector and maybe the surrounding media query, if present. They are not used to generate CSS properties themselves. Parsing the variants is a bit of grunt work and nothing really special. If we detect that a supposed variant doesn’t exist we can exit early already.

What’s more interesting than variants is the rule generation aspect. The majority of tailwind class names don’t feature a variant. Since tailwind mirrors a lot of CSS properties, the amount of potential matches we need to make is quite large. I’ve tried various approaches like matching all static tailwind class names up front, putting everything in an object with methods to use like a virtual function table and more. But in the end the fastest and I felt like the easiest to maintain was one giant dumb switch statement.

function parse(lexer, config, hasNegativePrefix) {
  const first = lexer.nextSegment()
  switch (first) {
    case “aspect”:
      //...
    case “block”:
      if (!lexer.isEnd) return // bail out
      return `display: block`
    case “inline”:
      if (lexer.isEnd) return `display: inline`
      const second = lexer.nextSegment();

      if (
        second !== “block” || second !== “flex” || second !== “table”
        || second !== “grid”
      ) {
        return // bail out
      }

      return `display: inline-${second}`

    // ...1000 lines more of this
  }
}

This might look like pretty standard parser code, but there are some interesting aspects. The obvious one is that at every step we check if we’re still on a valid path. This adds a lot of additional checks, but I found that the cost for these is offset by the gains of being able to bail out earlier. In some prior iterations I made a mistake in the extracting portion and ended up feeding way too many known false positive strings to this parse function. But because the parse function quickly bails out on invalid class names it took me a while to notice as it was still fast overall.

Of note is also the hasNegativePrefix argument that’s passed to the parse() function. Many numeric based properties like padding can receive negative values by prefixing the class name with a minus - character.

"pl-2"; // -> padding-left: 0.5rem;
"-pl-2"; // -> padding-left: -0.5rem;

The leading minus character is stripped before passing it to the parse() function, so that we can reuse the same case branches for both the normal and the negative case. It’s not shown here, but the parser also supports arbitrary values, the important declaration, color values with opacity and more.

Although I didn’t implement every single rule, all the syntax variations are supported. I did implement a fair share of the rules though, about 126 of them. That’s roughly 80% of the tailwind grammar. Even though this is mostly a prototype I wanted to get a better picture of how the parser would scale.

With the generated rules in hand we can now finally replace the @tailwind rule in the original CSS file. If we want it to be source map aware we can use Magic String.

With everything in place, here are the final measurements:

Extract: 98ms
Parse: 21ms
Total time: 192ms (including runtime startup time)

The whole project consists of 5 files (excluding tests) and is just shy of 3000 lines of code.

What about Rust?

The reason our little project here is faster than the og Tailwind CSS cli is that we sidestepped parsing anything with PostCSS completely and focuses on generating CSS rules as fast as possible. The Tailwind team is currently in the process of rewriting Tailwind CSS in Rust and from what I can gather they are already far along. I don’t have any numbers for that as it’s not yet released. What remains to be solved like with any JavaScript tool that is being rewritten to rust is what their plugin story will look like. Tailwind does support custom variants or full rules being defined in their config. Once it’s out it will be interesting to compare the two.

Conclusion

This was a fun little exploration to see what the architecture of Tailwind CSS tuned for performance would look like. Admittedly, this one took me way longer to write than previous articles because of the amount of prototyping involved to arrive at something I was satisfied with. Whatever the Tailwind CSS team decides to do, I’m really looking forward to that.

To me, Tailwind CSS is the jQuery of CSS. Not everyone likes it, but the positive effect it had on the web industry is undeniable. It enables a whole new generation of developers to get into web development.

I really appreciate what they’re trying to do, because it mirrors my own path to becoming a developer. When I started with web development jQuery was at its peak and without it I would have never touched JavaScript. It wasn’t until 2 years into my career that I took an interest in JavaScript itself and learned the fundamentals. Tailwind CSS is doing exactly that for today’s developers when it comes to CSS.

I’m really glad that they exist, even if their compiler could be faster.

Speeding up the JavaScript ecosystem - The barrel file debacle

2023-10-08T00:00:00Z

Let's imagine you are working on a big project with many files. You add a new file to work on a new feature and import a function from another directory into your code.

import { foo } from "./some/other-file";

export function myCoolCode() {
	// Pretend that this is super smart code :)
	const result = foo();
	return result;
}

Excited about finishing your feature, you run the code and realize that it takes an awfully long time to complete. The code you've written is pretty straight forward and shouldn't consume that much time. Concerned by this, you sprinkle in some measuring code to see how long your function took to do its thing.

import { foo } from "./some/other-file";

export function myCoolCode() {
	console.time();
	const result = foo();
	console.timeEnd();
	return result;
}

You run the code again, and to your surprise the measurements you inserted show that it's blazing fast™. You repeat the measuring steps, but this time insert the console.time() statements in the main entry file of your project and run the code again. But no dice, the logged measurements just confirm that your code itself is super fast. What is happening?

Well, strap in. This is the story of the devastating effects barrel files have on your code.

Gathering more information

The key piece of information we have obtained so far is that the runtime of the code isn't the issue. You measured it, and it was a fraction of the total time. This means we can assume that all the other time is wasted either before or after running our code. From experience when it comes to tooling, the time is usually spent before running the project code.

You got an idea: You remember hearing that some npm packages pre-bundle their code for performance reasons. Maybe this could help here? You decide to test that theory and bundle your code with esbuild into a single file. You purposely disable any forms of minifications, because you want your code to be as close as possible to the original source.

Upon completion, you then run the bundled file to repeat the experiment and voilá, it finishes in a blink of an eye. Out of curiosity, you measure the time it takes to run esbuild and run the bundled file together and notice that both of them combined are still quicker than running the original source code. Huh? What is going on?

Then it hits you: The main thing a bundler does is flatten and merge the module graph. What was once composed of thousands of files, is merged into a single file thanks to esbuild. This would be a strong indicator that the size of the module graph is the true problem here. And barrel files are the main cause of that.

Anatomy of a barrel file

Barrel files are files that only export other files and contain no code themselves. As a non-native speaker that term is confusing to me, but let's roll with it. In the days before editors had auto imports and other niceties, many developers tried to keep the number of import statements they had to write by hand to a minimum.

// Look at all these imports
import { foo } from "../foo";
import { bar } from "../bar";
import { baz } from "../baz";

This gave rise to a pattern where every folder got its own index.js file that merely re-exported code from other files in usually the same directory. In a way this amortized the manual typing work because once such a file is in place, all the other code only needs to reference one import statement.

// feature/index.js
export * from "./foo";
export * from "./bar";
export * from "./baz";

The previously shown import statements can now be collapsed into a single line.

import { foo, bar, baz } from "../feature";

After a while, this pattern spreads throughout the codebase and every folder in your project has an index.js file. Kinda neat, isn't it? Well, no.

Everything is not fine

In such a setup a module very likely imports another barrel file which pulls in a bunch of other files, which then imports yet another barrel file and so on. Ultimately, you typically end up importing every single file in your project through a spiderweb of import statements. And the bigger the project, the longer it takes to load all of these modules.

Ask yourself: What's quicker? Having to load 30k files or just 10? Probably only loading 10 files is faster.

It's a common misconception among JavaScript developers that modules would only be loaded when needed. This is not true, because doing so would break code relying on globals or module execution order.

// a.js
globalThis.foo = 123;

// b.js
console.log(globalThis.foo); // should log: 123

// index.js
import "./a";
import "./b";

If the engine wouldn't load the first ./a import, then the code would unexpectedly log undefined instead of 123.

Effects of barrel files on performance

It gets worse when you take tools like test runners in consideration. In the popular jest test runner, each test file is executed in its own child process. In effect, this means that every single test file constructs the module graph from scratch and has to pay for that cost. If constructing the module graph in a project takes 6s and you have - let's say - only 100 test files, then you waste 10 minutes in total to repeatedly construct the module graph. No test or any other code is being run during that time. It's just the time the engine needs to prepare the source code so that it can then be run.

Another area where barrel files gravely affect performance is any sort of import cycle linting rules. Typically linters are run on a file-by-file basis, which means the cost of constructing the module graph needs to be paid for every single file. It's not uncommon that this alone causes linting times to spiral out of control and suddenly linting takes a couple of hours in a bigger project.

To get some raw numbers, I've generated a project with files importing each other to get a better sense of the cost of constructing the module graph. Every file is empty and contains no code other than import statements. Timings are measured on my MacBook M1 Air (2020).

As you can see, loading fewer modules is very much worth it. Let's apply these numbers to a project with 100 test files where a test runner is used that spawns a new child process for each test file. Let's be generous here and say that our test runner can run 4 tests in parallel:

500 modules: 0.15s * 100 / 4 = 3.75s overhead
1000 modules: 0.31s * 100 / 4 = 7.75s overhead
10000 modules: 3.12s * 100 / 4 = 1:18m overhead
25000 modules: 16.81s * 100 / 4 = ~7:00m overhead
50000 modules: 48.44s * 100 / 4 = ~20:00m overhead

Since this is a synthetic setup, these are lowball numbers. In a real project these numbers are likely worse. Barrel files are not good when it comes to tooling performance.

What to do

Having only a handful of barrel files in your code is usually fine, but it gets problematic when every single folder has one. It's unfortunately not a rare occurrence in the JavaScript industry.

So if you work on a project which uses barrel files extensively, there is a free optimization you can apply that makes many tasks 60-80% faster:

Get rid of all barrel files.

Speeding up the JavaScript ecosystem - Polyfills gone rogue

2023-09-21T00:00:00Z

In the previous posts we looked at runtime performance and I thought it would be fun to look at node modules install time instead. A lot has been already written about various algorithmic optimizations or using more performant syscalls, but why do we even have this problem in the first place? Why is every node_modules folders so big? Where are all these dependencies coming from?

It all started when a buddy of mine noticed something odd with the dependency tree of his project. Whenever he updated a dependency, it would pull in several new ones and with each subsequent update the total number of dependencies grew over time.

 ├─┬ arraybuffer.prototype.slice 1.0.2
 │ └─┬ define-properties 1.2.1
 │   └── define-data-property 1.1.0
 ├─┬ function.prototype.name 1.1.6
 │ └─┬ define-properties 1.2.1
 │   └── define-data-property 1.1.0
 ├─┬ globalthis 1.0.3
 │ └─┬ define-properties 1.2.1
 │   └── define-data-property 1.1.0
 ├─┬ object.assign 4.1.4
 │ └─┬ define-properties 1.2.1
 │   └── define-data-property 1.1.0
 ├─┬ regexp.prototype.flags 1.5.1
 │ ├─┬ define-properties 1.2.1
 │ │ └── define-data-property 1.1.0
 │ └─┬ set-function-name 2.0.1
 │   └── define-data-property 1.1.0
 ├─┬ string.prototype.trim 1.2.8
 │ └─┬ define-properties 1.2.1
 │   └── define-data-property 1.1.0
 ├─┬ string.prototype.trimend 1.0.7
 │ └─┬ define-properties 1.2.1
 │   └── define-data-property 1.1.0
 └─┬ string.prototype.trimstart 1.0.7
   └─┬ define-properties 1.2.1
 	└── define-data-property 1.1.0

Now to be fair, there are valid reasons why a package might depend on an additional dependencies. Here, we began to notice a pattern though: The new dependencies were all polyfills for JavaScript functions that have long been supported everywhere. The Object.defineProperties method for example was shipped as part of the very first public Node 0.10.0 release dating back to 2013. Heck, even Internet Explorer 9 supported that. And yet there were numerous packages in that dependend on a polyfill for it.

Among the various packages that pulled in define-properties was eslint-plugin-react. It caught my eye, because it's very popular in the React ecosystem. Why does it pull in a polyfill for Object.defineProperties? There is no JavaScript engine that doesn't come with it already built in.

Polyfills that don’t polyfill

Reading the source of the packages revealed something even more bizarre: The polyfill functions were imported and called directly, rather than patching missing functionality in the runtime environment. The whole point of a polyfill is to be transparent to the user’s code. It should check if the function or method to patch is available and only add it if it’s missing. When there is no need for the polyfill it should do nothing. The odd thing to me is that the functions were used directly like a function from a library.

// Why is the `define` function imported directly?
var define = require("define-properties");
// ...

// and even worse, why is called directly?
define(polyfill, {
	getPolyfill: getPolyfill,
	implementation: implementation,
	shim: shim,
});

Instead they should call Object.defineProperties directly. The whole point of polyfills is to patch the environment not be called directly. Compare this to what a polyfill for Object.defineProperties is supposed to look like:

// Check if the current environment already supports
// `Object.defineProperties`. If it does, then we do nothing.
if (!Object.defineProperties) {
	// Patch in Object.defineProperties here
}

The most common place where define-properties was used was ironically inside other polyfills, which loaded even more polyfills. And before you ask, the define-properties package relies on even more dependencies than just itself.

var keys = require("object-keys");
// ...
var defineDataProperty = require("define-data-property");
var supportsDescriptors = require("has-property-descriptors")();

var defineProperties = function (object, map) {
	// ...
};

module.exports = defineProperties;

Inside eslint-plugin-react, that polyfill is loaded via a polyfill for Object.entries() to process their configuration:

const fromEntries = require("object.fromentries"); // <- Why is this used directly?
const entries = require("object.entries"); // <- Why is this used directly?
const allRules = require("../lib/rules");

function filterRules(rules, predicate) {
	return fromEntries(entries(rules).filter(entry => predicate(entry[1])));
}

const activeRules = filterRules(allRules, rule => !rule.meta.deprecated);

Doing a little bit of housekeeping

At the time of this writing installing eslint-plugin-react pulls in a whopping number of 97 dependencies in total. I was curious about how much of these were polyfills and began patching them out one by one locally. After all was done, this brought down the total number of dependencies down to 15. Out of the original 97 dependencies 82 of them are not needed.

Coincidentally, eslint-plugin-import which is equally popular in various eslint presets, shows a similar problems. Installing that fills up your node_modules folder with 87 packages. After another local cleanup pass I was able to cut down that number to just 17.

Filling up everyone's disk space

Now you might be wondering if you’re affected or not. I did a quick search and basically every widely popular eslint plugin or preset that you can think of is affected. For some reason this whole ordeal reminds me of the is-even/is-odd incident the industry had a while back.

Having so many dependencies makes it much harder to audit the dependencies of a project. It's a waste of space too. Case in point: Deleting all eslint plugins and presets in a project alone got rid of 220 packages.

pnpm -r rm eslint-plugin-react eslint-plugin-import eslint-import-resolver-typescript eslint-config-next eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-prettier prettier eslint-config-prettier eslint-plugin-react-hooks
Scope: all 8 workspace projects
.                                        | -220 ----------------------

Maybe we don't need that many dependencies in the first place. My mind went to this fantastic quote by the creator of the Erlang programming language:

You wanted a banana but what you got was a gorilla holding the banana and the entire jungle - Joe Armstrong

All I wanted was some linting rules. I didn’t want a bunch of polyfills that I don't need.

So you want to render colors in your terminal

2023-04-23T00:00:00Z

If you've been writing command line tools for other developers to use, there will come a time where the clarity of the output can be enhanced through colors. What appears to be simple on the surface gets a bit messy as soon as you dive into the details on how colors are supported in various terminal emulators. Funnily, much of this complexity is due to historical reasons which have been kept alive to this date.

Humble beginnings

In the early days of computing there were no terminal colors. Everything was rendered in either black or white. Demand grew for more complex rendering in the terminal and that's how ANSI escape codes were born. They represent a special set of character sequences that control cursor location, color, background color, font styling, and other options.

// This will print the string "foobar" in green to the terminal
console.log("\u001b[32mfoobar\u001b[39m");

...which looks like this in the terminal:

There is a catch though and that is that only a total of 16 colors are supported. Nearly half of them are lighter shades of existing colors, so the true perceived amount of colors feels even more limited. Despite those limitations, they are usually enough for most apps.

One cool aspect about this color palette is that pretty much every terminal emulator allows you to change the color values. This opens up the door for theming and styling the terminal to your likings. You can see a good overview of the default palette of various terminal emulators on Wikipedia.

The full list of supported colors is:

black
white
gray + light gray
red + light red
green + light green
yellow + light yellow
blue + light blue
magenta + light magenta
cyan + light cyan

All these colors can be used as foreground colors or as background colors. This is how they all render in my terminal.

Supporting all the colors

Over time computers advanced, and so did the richness of colors that developers wanted to use in their terminals. This led to the addition of an enhanced 8-bit color space which supports a whopping 256 colors. Suddenly, there wasn't only green and dark green anymore. You could now display shades of green!

But why stop there? Fast forward a couple of years and with the introduction of graphic cards, demand for even more colors grew. It became common for applications to render 16 or 24-bits of colors. It didn't take long for terminal emulators to follow suit. They jumped right to 24-bit colors which is often referred to as "true color" support. I'll spare you a screenshot since that would be too big for this post. Let me just say that the jump from 256 colors to 16.7 million colors is pretty big.

In summary, we ended up with 4 different color spaces:

black & white
Ansi, 16 colors
Ansi 256 colors
24-bit True Color

Detecting color support

This is the bit where it gets messy, because every terminal emulator does it slightly differently. There is no standardized way to detect which color space is supported. It's not just terminal emulators either, because today's developers expect the CI logs to be colored too. Most environments straight up don't tell you what kind of color space they support.

The most common way to detect color support is by checking the TERM and COLORTERM environment variables. CI systems can be detected by checking for the existence of the CI environment variable. Combine that with the knowledge about which operating system the program is running on, and we have a decent enough way to detect colors.

If COLORTERM is 24bit or truecolor, then you know for certain that 24-bit True Colors are supported. Detecting ANSI 256 is usually done by checking if $TERM ends with 256 or 256color. If True Colors are supported than ANSI 256 support is a given. Same is true for the basic ANSI escape codes. Again, this detection logic is neither perfect nor elegant, but it works pretty reliable in practice. The Windows Terminal on the other hand doesn't give you anything. Both environment variables are not set there. Therfore everyone simply assumes that the terminal supports full 24-bit colors, which is the case since Windows 10 revision 14931.

Name	OS	ANSI	ANSI 256	True Color	$TERM	$COLORTERM	$CI
Terminal.app	macOS	✅	✅	-	`xterm-256color`	-	-
iTerm	macOS	✅	✅	✅	`xterm-256color`	`truecolor`	-
Windows Terminal	Windows	✅	✅	✅	-	-	-
PowerShell	Windows	✅	✅	✅	-	-	-
GitHub Actions	Linux (Ubuntu)	✅	✅	✅	`dumb`	-	`true`

The crazy bit is that the only common terminal emulator that I came across that didn't support True Colors at the time of this writing was macOS's built in Terminal.app. It only supports up to ANSI 256.

CI systems are the real boss battle here, because they often advertise themselves as dumb terminals with no support for colors. Since developers expect the logs to contain colors, there is no other way than to ignore both TERM and COLORTERM variables. Instead color support is inferred by virtue of detecting that the code runs inside the CI.

Color conversions

The missing piece when it comes to colors is converting one color space to another. When a developer uses the notation for True Colors to print something to the terminal, we should at least be able to show some colors.

Here is what it looks like if you try to render True Colors in a terminal emulator that doesn't support them.

And here is the same colors converted down to the more limited ANSI 256 color space.

Sure, the colors are slightly different, but it's better than nothing. It's a "good enough" compromise that keeps the original intentions intact. As far as I know this is only needed for macOS's Terminal.app, which unfortunately is the one I happen to use the most. For some reason I haven't switched to another emulator so far.

Can we do better?

Despite all those advancements, it feels a little weird to have to be aware of ANSI escape codes as a developer. Most developers just want to set the text color or background color after all. You know browsers allow you to style console.log messages via plain CSS. What if we leveraged the same thing on the server? That's exactly what deno does. They got it right. They allow you to use the same API to print colors on the server.

console.log(
	"%cThis text is lime green %cand %cthis text has a red background",
	"color: #86efac",
	"",
	"background-color: red; color: white"
);

Rendered in Chrome's browser console:

The same code executed on the server with deno:

Conclusion

Sometimes it's all about getting the details right. For me colors have always been a huge part in making CLI output more readable. They can introduce an additional visual hierarchy that's not possible with mere character shapes. Fixing color detection support for some projects was a fun little investigation. Luckily, most of the complexity is already solved by existing libraries in the ecosystem, so that you don't have to work this out yourself.

Speeding up the JavaScript ecosystem - draft-js emoji plugin

2023-04-16T00:00:00Z

I received a very interesting issue via email from Josh Goldberg regarding a website that froze for about 2-3s. The website uses the draft-js rich text editor for some inputs and he was able to narrow it down to something going wrong in the emoji plugin for draft-js. So we decided to hop on a call and continue debugging together.

Capturing a quick recording via Chrome's profiler confirms the initial suspicions. Something is up with the emoji plugin. We can see a lot of frequent function calls at the bottom that take up the majority of time. Unfortunately, Chrome's profiler doesn't have some sort of "left-heavy" visualization like speedscope does. This makes it a little harder to see which function is worth investigating. The "left-heavy" is nicer for that as it merges similar callstacks into one.

Each individual call seemed fine and always ended up with calling into the regex engine. But the high number of calls were enough of a reason for concern. A cool thing about Chrome's profiler is that it can annotate source code lines with the sampled traces. This gives you an approximate time for how much each line took to execute. It's not 100% accurate due to the amount of transpilation being involved in frontend projects, but it's good enough to derive some early conclusions.

Aha! The two methods that consumed most of the time deal with regexes. It might have been tempting to conclude that the regexes itself were to blame, but I had a feeling that that was merely a symptom of a deeper problem. First thing we checked was how often this function was called. This can be done via incrementing a simple counter or by using console.count() directly.

  ns.escapeRegExp = function(string) {
+   console.count("escapeRegExp");
    return string.replace(/[-[\]{}()*+?.,;:&\\^$#\s]/g, "\\$&");
  };

  ns.replaceAll = function(string, find) {
+   console.count("replaceAll");
    var escapedFind = ns.escapeRegExp(find);
    var search = new RegExp("<object[^>]*>.*?<\/object>|<span[^>]*>.*?<\/span>|<(?:object|embed|svg|img|div|span|p|a)[^>]*>|("+escapedFind+")", "gi");
    // ...
  };

Turns out that the replaceAll method was called 7318 times whenever the page was loaded. Next, we checked what kind of arguments escapeRegExp was called with. The theory being that maybe it's called with the same arguments over and over again.

A minute later that hypothesis proved to be correct as it was escaping the same string over and over again. We know that this method is called from replaceAll, so let's check if we're always passing the same argument there. And sure enough, the first string argument received two different values, but the second find argument was always the same. That's the one that was later passed to escapeRegExp.

The immediate question that popped up was: "Who is calling replaceAll and why are they always passing the same arguments?"

Zooming into the profile again, we observed that all calls to replaceAll had toShort as a common ancestor.

Something very interesting was happening here in that the second argument passed to replaceAll didn't depend on arguments passed to toShort at all. And following the trail of unicodeCharRegex we got a clearer picture of what the purpose of the code here was. Like in popular chat apps like Slack, the plugin for draft-js allows you to type the text :smile: which is then automatically converted to a proper emoji "😀". But the reverse is also needed and that's what we were seeing here.

Finding a solution

Knowing more about the purpose of this code, we noticed that the the regex was built by iterating a big data structure of unicode characters and their metadata. This regex was then applied to the incoming text to match emojis and replace them with the shortcode. With every single call to toShort the regex would be constructed from scratch. It becomes a performance problem, because the unicode standard has a gazillion emojis with variations for skin tones and other things. So yeah, no wonder the resulting regex was huge.

Chrome's console is showing that the generated string from which the regex is constructed is bigger than 42kB alone.

As with most cases of expensive computations, we can avoid a lot of the work by caching the previous result. That way we don't need to recompute the same thing again and again. It's the least invasive fix one can make that doesn't require bigger changes to the architecture of the plugin. We made a PR and it reduced the blocking time from 2-3s down to <200ms in total. That's still a lot more than what we'd like, but that's already night and day in terms of user experience.

We ended our call together at this stage, but it made me wonder what else could be done if we didn't restrict ourselves to keep the current architecture.

Conclusion

If we step back for a second, it seems wasteful to always build up that regex whenever that module is loaded in the first place. The result is always the same, so an optimization would be to store the transformed result and use that from the get go in the plugin instead. That could be built whenever a new version of the plugin is released.

Another potential idea to pursue would be to use a handcrafted function to match emojis. It would allow you to narrow down the search space of potential matches very quickly, but it remains to verify that such an approach would be faster than a regex in this scenario. I think it's worth a shot.

EDIT: Fabio Spampinato shared an even better idea on twitter. Instead of constructing a >40kB regular expressions, we can leverage the recent unicode enhancements. This includes special unicode property escapes like Emoji_Presentation which allows you to match all emojis directly (example: /\p{Emoji_Presentation}/gu). With that we can get rid of all the regex generation code completly. Read more about that on MDN.

Overall this particular issue is a good reminder to profile our code from time to time. It's a reminder that even innocent looking functions can have a huge impact on performance.

Speeding up the JavaScript ecosystem - npm scripts

2023-03-19T00:00:00Z

If you’re working with JavaScript you’ve likely used the "scripts" field in package.json to set up common tasks for your project. Those scripts can be executed with npm run on the terminal. I noticed that I opted more and more to just call the underlying command directly instead of shelling out to npm run, mostly because it's noticeably faster. But what makes them so much slower in comparison? Time for a profiling session!

Loading only the code you need

What many developers don’t know is that the npm CLI is a standard JavaScript file and can be invoked like any other .js file. On macOS and Linux you can get the full path to the npm cli by running which npm. Dumping that file to the terminal reveals that it's a boring standard .js file. The only special thing is the first line which tells your shell with which program the current file can be executed with. Since we're dealing with a JavaScript file that would be node.

Because it's just a .js file we can rely on all the usual ways to generate a profile. My favorite one is node’s --cpu-prof argument. Combine that knowledge together and we can generate a profile from an npm script via node --cpu-prof $(which npm) run myscript. Loading that profile into speedscope reveals quite a bit about how npm is structured.

The majority of time is spent on loading all the modules that compose the npm cli. The time of the script that we’re running pales in comparison. We see a bunch of files which only seem to be necessary once certain conditions are met. An example of that would be code for formatting error messages that's only needed when an error occurred.

Such a case exists in npm where an exit handler is required eagerly. Let's require that module only when we need it.

  // in exit-handler.js
  const log = require('./log-shim.js')
- const errorMessage = require('./error-message.js')
- const replaceInfo = require('./replace-info.js')

  const exitHandler = err => {
    //...
    if (err) {
+     const replaceInfo = require('./replace-info.js');
+     const errorMessage = require('./error-message.js')
      //...
    }
  };

Comparing the profile after this change with the one without it doesn't show any difference in the total time taken. That is because the modules that we changed to be lazily loaded here are eagerly required elsewhere. To properly lazy load them we need to change all sites where it's required.

Next up I noticed that a bunch of code related to npm’s audit feature was loaded. This seems odd, since I’m not running anything related to auditing. Unfortunately for us, it’s not as easy as just moving some require calls around.

One class to rule them all

A recurring problem in various js tools is that they are composed of a couple of big classes that pull in everything instead of only the code you need. Those classes always start out small and with good intentions to be lean, but somehow they just get bigger and bigger. It becomes harder and harder to ensure that you're only loading the code you need. This reminds me of this quote from Joe Armstrong (creator of the Erlang programming language):

"You wanted a banana but what you got was a gorilla holding the banana and the entire jungle." – Joe Armstrong

Inside npm is an Arborist class which pulls in a lot of things that are only needed for specific commands. It pulls in things related to modifying the layout and packages in node_modules, auditing package versions and a bunch of other things that are not needed for the npm run command. If we want to optimize npm run we need to boot them off of the eagerly loaded modules list.

const mixins = [
	require("../tracker.js"),
	require("./pruner.js"),
	require("./deduper.js"),
	require("./audit.js"),
	require("./build-ideal-tree.js"),
	require("./load-workspaces.js"),
	require("./load-actual.js"),
	require("./load-virtual.js"),
	require("./rebuild.js"),
	require("./reify.js"),
	require("./isolated-reifier.js"),
];

const Base = mixins.reduce((a, b) => b(a), require("events"));
class Arborist extends Base {
	//...
}

For our purposes all the modules loaded in the mixins array, which the Arborist class later extends on, are not needed. We can drop all of them. This change gains us savings of about 20ms, which might not seem like much, but those savings add up. Like before, we need to check other places where those modules are required to ensure that we're really loading it on demand only.

Reducing the size of the module graph

Changes to a couple of require statements here and there are nice, but won't sway the numbers substantially. The bigger issue are dependencies which often have one main entry file which pulls in all the code of said module. Ultimately, the problem is that when the engine sees a bunch of top level import or require statements, it is going to parse and load those modules eagerly. No exceptions. But this is exactly what we want to avoid here.

A concrete example of that is the cleanUrl function that is imported from the npm-registry-fetch package. Like the name implies, that package is all about doing network stuff. But we don't do any sort of network requests in npm run when running a script. That's another 20ms saved. We don't need to display a progress bar either, so we can drop code for that too. Same is true for a bunch of other dependencies that the npm cli uses.

The amount of modules you load is a very real problem for these scenarios. It's no surprise that libraries for which start up time is critical have turned to bundlers to merge all their code into fewer files. Engines are pretty good with loading big blobs of JavaScript. The main reason we care so much about file size on the web is the cost of having to deliver those bytes over the network.

There are tradeoffs to this approach though. The bigger the file, the longer it takes to parse it, so there will be a threshold after which the parse cost of a single gigantic file is higher than splitting it up. As always: Measuring will show you if you hit that tradeoff. Another thing to consider is that bundlers cannot bundle code written for the CommonJS module system as efficiently as code that’s authored in ESM. Typically they introduce a lot of wrapper code around CommonJS modules which nullifies most of the benefits of bundling the code in the first place.

Sorting all the strings

With each reduction of the module graph the profile became less noisy and revealed other areas which could be improved. A particular call to a collaterCompare function caught my eye.

You might be thinking that 10ms isn’t worth it to spend time investigating it, but in this profile it's more of a "death by a thousand paper cuts" sort of thing. There is no single big entry that makes everything fast. So spending improving even smaller call sites is very much worth it. What’s interesting about this one for the collatorCompare function is that it’s intended purpose is to sort strings in a locale aware fashion. The implementation is split in two parts to achieve that: An initializing function and the function it returns which does the actual comparison.

// Simplified example of the code in @isaacs/string-locale-compare

const collatorCompare = (locale, opts) => {
	const collator = new Intl.Collator(locale, opts);
	// Always returns a new function that needs to be optimized from scratch
	return (a, b) => collator.compare(a, b);
};

const cache = new Map();
module.exports = (locale, options = {}) => {
	const key = `${locale}\n${JSON.stringify(options)}`;

	if (cache.has(key)) return cache.get(key);

	const compare = collatorCompare(locale, opts);
	cache.set(key, compare);
	return compare;
};

If we look at all the places this module is loaded at, we can see that we are only ever interested in sorting English strings and never pass any additional options aside from the locale. But because of the way this module is structured, every new require call will nudge folks to create a brand new comparison function that needs to be optimized all over again.

// Every require call immediately calls the "default" export with "en"
const localeCompare = require("@isaacs/string-locale-compare")("en");

But ideally we want everyone to use the same comparison function. With that in mind we can replace the code with a two-liner where we create the Intl.Collator once and create the localeCompare function only once too.

// We only ever need to construct the Collator class instance once
const collator = new Intl.Collator("en");
const localeCompare = (a, b) => collator.compare(a, b);

At one particular place, npm holds a sorted list of available commands. That list is hard coded and will never change at runtime. It only consists of ascii strings, so we can use plain old .sort() instead of our locale aware function.

  // This array only contains ascii strings
  const commands = [
    'access',
    'adduser',
    'audit',
    'bugs',
    'cache',
    'ci',
    // ...
- ].sort(localeCompare)
+ ].sort()

With this change the time it takes to call that function is close to 0ms. Another 10ms saved since this was the last place which loaded this module eagerly.

To note here is that at this point we’ve made npm run twice as fast. We’re now down to ~200ms from the ~400ms we started with. Looking good!

Setting process.title is expensive

Another function call that jumped out was this call to a setter for a mysterious title property. 20ms for setting a property seems expensive.

The implementation of that setter is surprisingly simple:

class Npm extends EventEmitter {
	// ...
	set title(t) {
		// This line is the culprit
		process.title = t;
		this.#title = t;
	}
}

Changing the title of the current running process seems to be a pretty expensive operation. This feature is really useful though, because it makes it easier to spot specific npm processes in the task manager when you have multiple ones running at the same time. For the sake of this investigation I didn’t look further and commented that part out. Nonetheless, I think it might be worth to look deeper into what's making it so costly.

Globbing log files

Another entry in the profile that drew my attention was a call to another string sorting function inside the glob module. It’s pretty odd that we’re even globbing here at all when all we want to do is run npm scripts. The glob module is used to crawl the file system for files matching a user defined pattern, but why would we need that? The majority of time seems to be spent not searching the file system but rather sorting strings ironically.

This function is only called once with a simple array of 11 strings and sorting that should be instant. Strangely, the profile showed that this took ~10ms.

// Sorting this array somehow takes 10ms
[
	"/Users/marvinhagemeister/.npm/_logs/2023-03-18T20_06_53_324Z-debug-0.log",
	"/Users/marvinhagemeister/.npm/_logs/2023-03-18T20_07_35_219Z-debug-0.log",
	"/Users/marvinhagemeister/.npm/_logs/2023-03-18T20_07_36_674Z-debug-0.log",
	"/Users/marvinhagemeister/.npm/_logs/2023-03-18T20_08_11_985Z-debug-0.log",
	"/Users/marvinhagemeister/.npm/_logs/2023-03-18T20_09_23_766Z-debug-0.log",
	"/Users/marvinhagemeister/.npm/_logs/2023-03-18T20_11_30_959Z-debug-0.log",
	"/Users/marvinhagemeister/.npm/_logs/2023-03-18T20_11_42_726Z-debug-0.log",
	"/Users/marvinhagemeister/.npm/_logs/2023-03-18T20_12_53_575Z-debug-0.log",
	"/Users/marvinhagemeister/.npm/_logs/2023-03-18T20_17_08_421Z-debug-0.log",
	"/Users/marvinhagemeister/.npm/_logs/2023-03-18T20_21_52_813Z-debug-0.log",
	"/Users/marvinhagemeister/.npm/_logs/2023-03-18T20_24_02_611Z-debug-0.log",
];

The implementation looks pretty harmless too.

function alphasort(a, b) {
	return a.localeCompare(b, "en");
}

But maybe we can use the Intl.Collator object instead that we used earlier to compare these strings.

const collator = Intl.Collator("en");
function alphasort(a, b) {
	return collator.compare(a, b);
}

And that did the trick. I’m not entirely sure why String.prototype.localeCompare is slower in comparison. It definitely sounds fishy. But I can reliably verify the speed difference on my end. The Intl.Collator approach is consistently faster for this particular call.

The bigger fish is that searching the file system for log files seems at odds with our intentions. It’s super useful that a log file is written and cleared if the command was successful, but shouldn’t we know the names of the files we wrote if we are the ones who created them in the first place? I took a stab at changing that, but for the sake of this article I decided to comment that out and continue the investigation.

At this point we’re down to ~138ms from the ~400ms at the beginning. Although that’s already a pretty nice improvement we could do a lot better.

Deleting all the things

I felt like I needed to become a little more aggressive with deleting or uncommenting code that’s not related to running npm scripts. We’ve done our fair share so far and we could continue on that path, but I got curious about what the northstar time is that we should shoot for. The basic goal is to only load code that is absolutely necessary to execute npm scripts. Everything else is merely overhead and time wasted.

So I went out and wrote a short script that does the bare minimum necessary to run npm scripts. In the end I got it down to about 22ms, which is about 18x faster than the 400ms we started with. I'm pretty happy with that although 22ms still feels like a lot of time compared to what it does. It's certainly something where other languages like Rust excel at in comparison. Regardless, there is a point to be made that 22ms is fast enough for now.

Conclusion

On the surface it seems strange that we spent that much time making the npm run command about 380ms faster. However, if you think about how often that command is executed by developers all over the world and how often it is executed inside a CI, those savings add up pretty quickly. It's nice to have have more snappier npm scripts too for local development too, so there is definitely the angle of personal benefit

But the big elephant in the room remains: There is no easy way to short circuit the module graph. All JavaScript tools I looked at so far have this problem. Some tools have this more pronounced and others are less affected. The overhead of resolving and loading a bunch of modules is very real. I’m not sure what the long term solution to that will be or if that is solvable by JavaScript engines themselves.

Until a proper solution is found, a viable workaround that we can apply today is bundling the code when publishing it to npm. I’m secretly hoping though that this isn’t the only viable path forward and that all runtimes improve on that front. The less tooling we have to deal with, the more beginner friendly we are as an ecosystem.

Speeding up the JavaScript ecosystem - eslint

2023-02-05T00:00:00Z

We've talked quite a bit about linting in the past two posts of this series, so I thought it's time to give eslint the proper limelight it deserves. Overall eslint is so flexible, that you can even swap out the parser for a completely different one. That's not a rare scenario either as with the rise of JSX and TypeScript that is frequently done. Enriched by a healthy ecosystem of plugins and presets, there is probably a rule for every use case out there and if there isn't, the excellent documentation guides you on how to create your own rules. That's one thing I want to highlight here as it's a project that has stood the test of time.

But this also poses a problem for performance profiling as due to the vastness of the configuration flexibility two projects can have a widely different experience when it comes to linting performance. We need to start somewhere though, so I figured what better way to start our investigation than to look at the linting setup used in the eslint repository itself!

Using eslint to lint eslint

Their repository uses a task runner abstraction to coordinate common build tasks, but with a little bit of digging we can piece together the command that is run for the "lint" task, specifically for linting JavaScript files.

node bin/eslint.js --report-unused-disable-directives . --ignore-pattern "docs/**"

Neat, here you have it: Eslint is using eslint to lint their codebase! Like in both previous articles of this series we'll be generating a *.cpuprofile via node's built-in --cpu-prof argument and we'll be loading that into Speedscope for further analysis. A few seconds later (22s to be exact), we are ready to dive in!

By merging similar call-stacks together we get a much clearer picture of where the time is being spent. This is typically referred to as a "left-heavy" visualization. This is not to be confused with your standard flamegraph where the x-axis represents when a call happened. Instead, in this style the x-axis represents time consumed of the total time, not when it happened. To me it's one of the main benefits of Speedscope and it feels much snappier too. Wouldn't have expected any less since it's written by a few devs from Figma who are known for their excellence in engineering in our industry.

Immediately we can make out a few key areas where the linting setup in eslint's repository is spending time. The main things that stand out is that a good chunk of the total time is spent on rules dealing with JSDoc as inferred from their function names. Another interesting aspect is that there are two different parsers running at various times during the lint task: esquery and acorn. But my curiosity was piqued by the JSDoc rules taking so long.

One particular BackwardTokenCommentCursor entry seems to be of interest as it's the largest block of the bunch. Following the attached file location to the source, it seems to be a class that holds the state of where we are in a file. As a first measure I added a plain counter that increments whenever that class is instantiated and ran the lint task again.

On getting lost 20 million times

All in all, this class has been constructed more than 20 million times. That seems quite a lot. Remember, any object or class we instantiate takes up memory, and that memory later needs to be cleaned up. We can see the consequence of that in the data where garbage collection (the act of cleaning up memory) takes 2.43s in total. That's not good.

Upon creating a new instance of that class it calls two functions which both seem to kick off a search. Without knowing more about what it's doing the first one can be ruled out though as it doesn't contain any form of loops. From experience, loops are usually a prime suspect to investigate for performance, so I usually start my search there.

The second function though, called utils.search(), contains a loop. It loops over the stream of tokens that were parsed from the contents of the file we were linting at the time. A token is the smallest building block of a programming language and you can think of them being the "words" of a language. For example in JavaScript the word "function" is typically represented as one function token, and so is a comma or a single semicolon. In this utils.search() function we seem to be concerned with finding the nearest token to our current position in the file.

exports.search = function search(tokens, location) {
	const index = tokens.findIndex(el => location <= getStartLocation(el));
	return index === -1 ? tokens.length : index;
};

To do that the search is done on the token array via JavaScript's native .findIndex() method. The algorithm is described as:

The findIndex() is an iterative method. It calls a provided callbackFn function once for each element in an array in ascending-index order, until callbackFn returns a truthy value.

Given that the array of tokens grows with the amount of code we have in a file, that doesn't sound ideal. There are more efficient algorithms to search a value in an array that we can use rather than going through every element in the array. Replacing that line with a binary search for example cuts the time in half.

Whilst a 50% reduction seems good, it still doesn't address that this code is called 20 million times. To me that's the real issue. We're more or less trying to reduce the impact of the symptoms here instead of addressing the underlying problem. We're already iterating through the file so we should know exactly where we are. Changing that requires a more invasive refactor though and would be too much to explain for this blog post. Seeing that this wouldn't be an easy fix I checked what else is worthy of attention in the profile. The long violet bars in the center are hard to miss, not just because they're a different color, but because they take up a lot of time and are not drilled down into hundreds of smaller function calls.

The selector engine

The callstack in speedscope points to a project called esquery which I hadn't heard about prior to this investigation. It's an older project whose goal is to be able to find a specific object in the parsed code through a small selector language. If you squint a little you can see the strong resemblance to CSS selectors. And they work the same way here, just that we're not finding a specific HTML element in the DOM tree, but rather an object in another tree structure. It's the same idea.

The traces indicate that the npm package ships with minified source code. Mangled variable names which are typically a single character strongly hint at such a process being in place. Luckily for me, the package also ships an unminified variant as well so I just modified the package.json to point at that instead. Another run later and we're greeted with the following data:

Much better! A thing to keep in mind with unminified code is that it performs about 10-20% slower than the minified variant. That's a rough approximate range which I've measured many times throughout my career when comparing the performance of minified to unminified code. Nonetheless, the relative timings stay the same, so it remains perfect for our investigation. With that the getPath function seems like something that could use a little help.

function getPath(obj, key) {
	var keys = key.split(".");

	var _iterator = _createForOfIteratorHelper(keys),
		_step;

	try {
		for (_iterator.s(); !(_step = _iterator.n()).done; ) {
			var _key = _step.value;

			if (obj == null) {
				return obj;
			}

			obj = obj[_key];
		}
	} catch (err) {
		_iterator.e(err);
	} finally {
		_iterator.f();
	}

	return obj;
}

Outdated transpilation will haunt us for a long time

If you've been around the JavaScript tooling space for a while these functions look awfully familiar. _createForOfIteratorHelper is with 99.99% certainty a function that was inserted by their publishing pipeline and not by the authors of this library. When for-of loops were added to JavaScript it took a while until it was supported everywhere.

Tools that downtranspile modern JavaScript features tend to err on the side of caution and rewrite the code in a very conservative way. In this case we know that we're splitting a string into an array of strings. To loop over that using a full blown iterator is totally overkill and a boring standard for loop would've been all that was needed. But since tools are not aware of that, they went with the variant that covers the most scenarios possible. Here is the original code for comparison:

function getPath(obj, key) {
	const keys = key.split(".");
	for (const key of keys) {
		if (obj == null) {
			return obj;
		}
		obj = obj[key];
	}
	return obj;
}

In today's world for-of loops are supported everywhere, so I patched the package again and swapped out the function implementation with the original one in the source. This one single change saves about 400ms. I'm always impressed by how much CPU time we burn on wasteful polyfills or outdated downtranspilation. You'd think that it makes much less of a difference, but then you came across a case such as this where the numbers paint a different picture. For what it's worth I also measured replacing the for-of loop with a standard for loop.

function getPath(obj, key) {
	const keys = key.split(".");
	for (let i = 0; i < keys.length; i++) {
		const key = keys[i];
		if (obj == null) {
			return obj;
		}
		obj = obj[key];
	}
	return obj;
}

Surprisingly, this netted another 200ms improvement compared to the for-of variant. I guess even today, for-of loops are harder to optimize for engines. That reminds me of a past investigation Jovi and I did into a sudden slow down in the parsing speed of the graphql package when they made a new release in which they switched to for-of loops.

It's something a v8/gecko/webkit engineer can properly verify, but my assumption would be that it still has to invoke the iterator protocol as that could have been globally overwritten, which would change the behavior for every single Array. It's probably something like that.

Whilst we got some quick wins out of those changes, it's still far from ideal. Overall the function remains a top contender to be improved as it is alone responsible for a couple of seconds of the total time. Applying the quick counter hack again reveals that it's called about 22k times. For sure a function that's somewhat in the "hot" path.

Of particular note in many performance intensive code that deals with strings revolves around the String.prototype.split() method. This will effectively iterate over all characters, allocate a new array and then iterate over that, all of which could be done in a single iteration.

function getPath(obj, key) {
	let last = 0;
	// Fine because all keys are ASCII and not unicode
	for (let i = 0; i < key.length; i++) {
		if (obj == null) {
			return obj;
		}

		if (key[i] === ".") {
			obj = obj[key.slice(last, i)];
			last = i + 1;
		} else if (i === key.length - 1) {
			obj = obj[key.slice(last)];
		}
	}

	return obj;
}

This rewrite had a strong impact on its performance. When we started getPath took 2.7s in total and with all optimizations applied we managed to get that down to 486ms.

Continuing with the matches() function, we see a lot of overhead created by weird for-of downtranspilation, similar to what we've seen earlier. To save some time I just went on github and copied the function from the source code directly. Since matches() is even more prominent in the traces, this change alone saves a full 1s.

So many libraries in our ecosystem suffer from this issue. I really wish there was a way to update them all with one click. Maybe we need a reverse transpiler which detects down transpilation patterns and converts it back to modern code again.

I reached out to jviide to see if we could optimize matches() further. With his additional changes we were able to make the whole selector code about 5x faster compared to the original unmodified state. What he basically did is get rid of a bunch of overhead in the matches() function which allowed him to simplify a couple of related helper functions too. For example he noticed that template strings were down transpiled poorly.

// input
const literal = `${selector.value.value}`;

// output: down transpiled, slow
const literal = "".concat(selector.value.value);

He went even a step further by parsing each new selector into a chain of function calls on the fly and caching the resulting wrapper function. This trick netted him another hefty speedup for the selector engine. I highly recommend checking out his changes. We haven't opened a PR because esquery seems to be unmaintained at this point.

EDIT: We did open a PR in the end.

Bailing out early

Sometimes it's good to take a step back and tackle the problem from a different angle. So far we looked at implementation details, but what kind of selectors are we actually dealing with? Is there potential to short circuit some of them? To test that theory I first needed to get a better overview of the kind of selectors that are being processed. Unsurprisingly, the majority of selectors were short. A couple of them though are quite the character soup. This for example here is a single selector:

VariableDeclaration:not(ExportNamedDeclaration > .declaration) > VariableDeclarator.declarations:matches(
  [init.type="ArrayExpression"],
  :matches(
	[init.type="CallExpression"],
[init.type="NewExpression"]
  )[init.optional!=true][init.callee.type="Identifier"][init.callee.name="Array"],
[init.type="CallExpression"][init.optional!=true][init.callee.type="MemberExpression"][init.callee.computed!=true][init.callee.property.type="Identifier"][init.callee.optional!=true]
	:matches(
  	[init.callee.property.name="from"],
  	[init.callee.property.name="of"]
)[init.callee.object.type="Identifier"][init.callee.object.name="Array"],
[init.type="CallExpression"][init.optional!=true][init.callee.type="MemberExpression"][init.callee.computed!=true][init.callee.property.type="Identifier"][init.callee.optional!=true]:matches(
  	[init.callee.property.name="concat"],
  	[init.callee.property.name="copyWithin"],
  	[init.callee.property.name="fill"],
  	[init.callee.property.name="filter"],
  	[init.callee.property.name="flat"],
  	[init.callee.property.name="flatMap"],
  	[init.callee.property.name="map"],
  	[init.callee.property.name="reverse"],
  	[init.callee.property.name="slice"],
  	[init.callee.property.name="sort"],
  	[init.callee.property.name="splice"]
	)
  ) > Identifier.id

This is certainly an example where I feel like we went a little off the rails. I don't want to be the person who has to debug that thing when it isn't matching correctly. That's my main gripe with any form of custom domain specific languages. They usually don't come with tooling support at all. If we stay in JavaScript-land instead we can inspect the value at any time at any step with a proper debugger. Whilst the previous string selector example is a bit extreme, the majority of selectors look like this:

BinaryExpression

or:

VariableDeclaration

That's it. Most of the selectors just want to know if the current AST node is of a certain type. Nothing more. For that we don't really need a whole selector engine. What if we introduced a fast path for that and bypassed the selector engine completely?

class NodeEventGenerator {
	// ...

	isType = new Set([
		"IfStatement",
		"BinaryExpression",
		// ...etc
	]);

	applySelector(node, selector) {
		// Fast path, just assert on type
		if (this.isType.has(selector.rawSelector)) {
			if (node.type === selector.rawSelector) {
				this.emitter.emit(selector.rawSelector, node);
			}

			return;
		}

		// Fallback to full selector engine matching
		if (
			esquery.matches(
				node,
				selector.parsedSelector,
				this.currentAncestry,
				this.esqueryOptions
			)
		) {
			this.emitter.emit(selector.rawSelector, node);
		}
	}
}

Since we're already short circuiting the selector engine, I became curious about how a stringified selector would fare against one written as a plain JavaScript function. My gut told me that a selector written as a simple JavaScript condition would be way easier to optimize for engines.

Rethinking selectors

A selector engine is very useful if you need to pass traversal commands across language barriers like we do with CSS in the browser. It never is free though, as a selector engine always needs to parse the selector to deconstruct what we should do, and then build some logic on the fly to execute that parsed thing.

But inside eslint we're not crossing any language barriers. We stay in JavaScript land. Therefore we don't gain anything performance-wise by converting query instructions into a selector and parsing them back into something we can run again. Rather, we consume about 25% of the total linting time for parsing and executing selectors. A new approach was needed.

Then it hit me.

A selector is conceptually nothing more than a "description" to get a find elements based on criterias it holds. That could be a lookup in a tree or a flat data structure like an array. If you think about it, even the callback function in a standard Array.prototype.filter() call is a selector. We're selecting values out of a collection of items (=Array) and picking only the values we care about. What we're doing with the esquery is exactly the same thing. Out of a bunch of objects (=AST nodes), we're picking out the ones which match a certain criteria. That's a selector! So what if we avoided the selector parsing logic and used a plain JavaScript function instead?

// String based esquery selector
const esquerySelector = `[type="CallExpression"][callee.type="MemberExpression"][callee.computed!=true][callee.property.type="Identifier"]:matches([callee.property.name="substr"], [callee.property.name="substring"])`;

// The same selector as a plain JS function
function jsSelector(node) {
	return (
		node.type === "CallExpression" &&
		node.callee.type === "MemberExpression" &&
		!node.callee.computed &&
		node.callee.property.type === "Identifier" &&
		(node.callee.property.name === "substr" ||
			node.callee.property.name === "substring")
	);
}

Let's give this a go! I wrote a few benchmarks to measure the time difference of these two approaches. A little later and the data popped up on my screen.

What	`foo.substr(1, 2)` ops/sec
esquery	422,848.208
esquery (optimized)	3,036,384.255
Plain JavaScript function	66,961,066.5239

Looks like the pure JavaScript function variant easily outperforms the string based one. It's vastly superior. Even after spending all this time on making esquery faster, it's nowhere near the JavaScript variant. In cases where the selector doesn't match and the engine can bail out earlier it was still 30x slower than a plain function. This little experiment confirmed my assumption that we're paying quite of time for the selector engine.

The impact of third-party plugins and presets

Although there is much more room for optimizations visible in the profile from eslint's setup, I began to wonder if I'm spending time optimizing the right thing. Did the same issues we've seen so far in eslint's own linting setup occur in other linting setups too? One of the key strengths of eslint has always been its flexibility and support for third party linting rules. Looking back, pretty much every project I worked on had a couple of custom linting rules and about 2-5 additional eslint plugins or presets installed. But what's more important is that they switched out the parser completely. A quick glance at the npm download stats highlights a trend in replacing eslint's built-in parser:

Package	npm downloads (weekly)	%
`eslint`	31.718.905	100%
`@typescript-eslint/parser`	23.192.767	73%
`@babel/eslint-parser`	6.057.110	19%

If those numbers are to be believed, it would mean that only 8% of all eslint users use the built-in parser. It also shows how ubiquitous TypeScript has become, making up the lionshare of eslint's total user base with 73%. We don't have data on whether users of the babel parser use it for TypeScript too. My guess would be that a portion of them do that and that the total number of TypeScript users is actually even higher.

After profiling a few different setups in various open source repositories, I settled on the one from vite which contains a good bunch of the patterns that were present in other profiles too. Its codebase is written in TypeScript and eslint's parser has been replaced accordingly.

Like before, we can make out various areas in the profile showing where the time is spent. There is an area that hints at a conversion from TypeScript's format to the one eslint understands taking quite a bit of time. Something odd is happening with the configuration loading too, as it never should take up that much time as it does here. And we found an old friend, the eslint-import-plugin and eslint-plugin-node which seem to kickoff a bunch of module resolution logic.

The interesting bit here though is that the overhead of the selector engine doesn't show up at. There are some instances of an applySelector function being called, but it barely consumes any time in the bigger picture.

The two third party plugins that always seem to pop up and take a considerable time to execute are eslint-plugin-import and eslint-plugin-node. Whenever one or both of these plugins were active, it really showed in the profiling data. Both cause heavy filesystem traffic as they try to resolve a bunch of modules, but don't cache the results. We wrote a lot about that in part 2 of this series, so I won't go into more detail on that.

Converting all the AST nodes

We'll start with the TypeScript conversion happening at the beginning. Our tools parse the code we provide to them into a data structure that is known as an Abstract-Syntax-Tree, in short: AST. You can think of that as being the building blocks that all our tooling works with. It tells information like: "hey, here we declare a variable and it has this name and that value", or "here is an if-statement with this condition, that guards that code-block", etc.

// `const foo = 42` in AST form is something like:
{
  type: "VariableDeclaration",
  kind: "const",
  declarations: [
    {
      kind: "VariableDeclarator",
      name: {
        type: "Identifier",
        name: "foo",
      },
      init: {
        type: "NumericLiteral",
        value: 42
      }
  ]
}

You can see for yourself how our tools parse code on the excellent AST Explorer page. I highly recommend visiting that and playing around with various code snippets. It gives you a good understanding of how similar or often different the AST format of our tools are.

However, in eslint's case there is a problem with that. We want rules to work regardless of the parser we've chosen. When we activate the no-console rule we want it to work across all of them and not force each rule to be rewritten for every single parser out there. Essentially, what we need is a shared AST format that we all can agree on. And that's exactly what eslint does. It expects every AST node to match the estree spec which codifies how each AST node should look. It's a spec that has been around for quite a while and many JavaScript tools started out with. Even babel is build on that, but has a few documented deviations since then.

But therein lies the crux of the problem when you're using TypeScript. TypeScript's AST format is very different as it also needs to account for nodes representing the types itself. Some constructs are represent differently internally too as it makes things easier for TypeScript itself. That means every single TypeScript AST node has to be converted to the format eslint understands. That conversion takes time. In this profile that accounts for ~22% of the total time. The reason it takes so long is not just the traversal alone, but also that with every conversion we'll be allocating new objects. We basically have two copies in different AST formats in memory.

Maybe babel's parser is faster? What if we swapped out @typescript-eslint/parser with @babel/eslint-parser?

What	Parse time
`@typescript-eslint/parser`	2.1s
`@babel/eslint-parser` + `@babel/preset-typescript`	0.6s

Turns out that doing just that saves us quite a bit of time. Interestingly, this change also cut down the config loading time by a good chunk. The improvement to the config load time is probably due to babel's parser being spread out in fewer files.

Note that whilst the babel parser is (at the time of this writing) noticeably faster, it doesn't support type-aware linting. That's a feature exclusive to @typescript-eslint/parser. This opens up the possibilities for rules like their no-for-in-array rule, which can detect if the variable you're iterating over in a for-in loop is actually an object instead of an array. So you might want to continue using @typescript-eslint/parser. If you are confident that you don't use any of their rules though and you are just looking for eslint to be able to understand TypeScript's syntax, plus be a little quicker to lint, then switching to babel's parser is a good option.

Bonus round: What would an ideal linter look like?

Around this point I stumbled upon a discussion about the future of eslint, with performance being one of the top priorities. There are some great ideas put forth in there, especially about introducing the notion of a session to allow for full program linting vs on a per file basis like it is done today. Given that around at least 73% of eslint users use it to lint TypeScript code, a tighter integration that requires less AST conversion would also be huge in regards to performance.

There is also some chatter about a rust port, which piqued my curiosity on how fast current rust-based linters for JavaScript are. The only one that seems to be somewhat production ready and able to parse a large portion of the TypeScript grammar is rslint.

Besides rslint, I also began to wonder what a simple linter in pure JavaScript would look like. One that didn't have a selector engine, didn't require constant AST conversion, and just the necessities to parse code and check various rules on it. So I wrapped babel's parser with a very simple API and added custom traversal logic to walk the AST tree. I didn't pick babel's own traversal functions because they cause lots of allocations with every iteration and are built on generators which is a little slower than not using generators. Also tried it with a few custom JavaScript/TypeScript parsers that I wrote myself over the years which originated from porting esbuild's parser to JavaScript a couple of years back.

With that said, here are the numbers when running them all on vite's repository (144 files).

What	Time
eslint (JavaScript)	5.85s
Custom linter (JavaScript)	0.52s
rslint (rust based)	0.45s

Based on these numbers I'm fairly confident that we can get very close to rust's performance with just JavaScript based on this little experiment.

Conclusion

Overall, the eslint project has a very bright future ahead. It's one of the most successful OSS projects and it has found the secret of getting a good amount of funding. We looked at a couple of things that would make eslint faster, and there are lots more areas to look into that weren't covered here.

The "future of eslint" discussion contains a lot of great ideas that would make eslint better and potentially faster. I think the tricky bit is avoiding trying to fix every problem at once as that's often doomed to fail in my experience. Same goes for a ground up rewrite. Instead, I think that the current code base is a perfectly good starting point, ready to be shaped into something even more awesome.

From an outsiders perspective, there are some key decisions to make. Like, does it make sense at this point to keep supporting string based selectors? If yes, does the eslint team have the capacity to take on maintenance of esquery and give it some much needed love? And what about native TypeScript support given that the npm download counts point at 73% of eslint users being TypeScript users?

Whatever will happen, I have strong confidence in their team and the ability to execute their vision. I'm excited for the future of eslint!

Speeding up the JavaScript ecosystem - module resolution

2023-01-15T00:00:00Z

In part 1 of this series we found a few ways to speed various libraries used in JavaScript tools. Whilst those low level patches moved the total build time number by a good chunk, I was wondering if there is something more fundamental in our tooling that can be improved. Something that has a greater impact on the total time of common JavaScript tasks like bundling, testing and linting.

So over the next couple of days I collected about a dozen CPU profiles from various tasks and tools that are commonly used in our industry. After a bit of inspection, I came across a repeating pattern that was present in every profile I looked at and affected the total runtime of these tasks by as much as 30%. It’s such a critical and influential part of our infrastructure that it deserves to have its own blog post.

That critical piece is called module resolution. And in all the traces I looked at it took more time in total than parsing source code.

The cost of capturing stack traces

It all started when I noticed that the most time consuming aspect in those traces was spent in captureLargerStackTrace an internal node function responsible for attaching stack traces to Error objects. That seemed a bit out of the ordinary, given that both tasks succeeded without showing any signs of errors being thrown.

After clicking through a bunch of occurrences in the profiling data a clearer picture emerged as to what was happening. Nearly all of the error creations came from calling node’s native fs.statSync() function and that in turn was called inside a function called isFile. The documentation mentions that fs.statSync() is basically the equivalent to POSIX’s fstat command and commonly used to check if a path exists on disk, is a file or a directory. With that in mind we should only get an error here in the exceptional use case when the file doesn’t exist, we lack permissions to read it or something similar. It was time to take a peek at the source of isFile.

function isFile(file) {
	try {
		const stat = fs.statSync(file);
		return stat.isFile() || stat.isFIFO();
	} catch (err) {
		if (err.code === "ENOENT" || err.code === "ENOTDIR") {
			return false;
		}
		throw err;
	}
}

From a quick glance it’s an innocent looking function, but was showing up in traces nonetheless. Noticeably, we ignore certain error cases and return false instead of forwarding the error. Both the ENOENT and ENOTDIR error codes ultimately mean that the path doesn’t exist on disk. Maybe that’s the overhead we’re seeing? I mean we’re immediately ignoring those errors here. To test that theory I logged out all the errors that the try/catch-block caught. Low and behold every single error that was thrown was either a ENOENT code or an ENOTDIR code.

A peek into node’s documentation of fs.statSync reveals that it supports passing a throwIfNoEntry option that prevents errors from being thrown when no file system entry exists. Instead it will return undefined in that case.

function isFile(file) {
	const stat = fs.statSync(file, { throwIfNoEntry: false });
	return stat !== undefined && (stat.isFile() || stat.isFIFO());
}

Applying that option allows us to get rid of the if-statment in the catch block which in turn makes the try/catch redundant and allows us to simplify the function even further.

This single change reduced the time to lint the project by 7%. What’s even more awesome is that tests got a similar speedup from the same change too.

The file system is expensive

With the overhead of stack traces of that function being eliminated, I felt like there was still more to it. You know, throwing a couple of errors shouldn’t really show up at all in traces captured over the span of a couple of minutes. So I injected a simple counter into that function to get an idea how frequently it was called. It became apparent that it was called about 15k times, about 10x more than there were files in the project. That smells like an opportunity for improvement.

To module or not to module, that is the question

By default there are three kind of specifiers for a tool to know about:

Relative module imports: ./foo, ../bar/boof
Absolute module imports: /foo, /foo/bar/bob
Package imports foo, @foo/bar

The most interesting of the three from a performance perspective is the last one. Bare import specifiers, the ones that don’t start with a dot . or with a slash /, are a special kind of import that typically refer to npm packages. This algorithm is described in depth in node’s documentation. The gist of it is that it tries to parse the package name and then it will traverse upwards to check if a special node_modules directory is present that contains the module until it reaches the root of the file system. Let’s illustrate that with an example.

Let’s say that we have a file located at /Users/marvinh/my-project/src/features/DetailPage/components/Layout/index.js that tries to import a module foo. The algorithm will then check for the following locations.

/Users/marvinh/my-project/src/features/DetailPage/components/Layout/node_modules/foo/
/Users/marvinh/my-project/src/features/DetailPage/components/node_modules/foo/
/Users/marvinh/my-project/src/features/DetailPage/node_modules/foo/
/Users/marvinh/my-project/src/features/node_modules/foo/
/Users/marvinh/my-project/src/node_modules/foo/
/Users/marvinh/my-project/node_modules/foo/
/Users/marvinh/node_modules/foo/
/Users/node_modules/foo/

That’s a lot of file system calls. In a nutshell every directory will be checked if it contains a module directory. The amount of checks directly correlates to the number of directories the importing file is in. And the problem is that this happens for every file where foo is imported. Meaning if foo is imported in a file residing somewhere else, we’ll crawl the whole directory tree upwards again until we find a node_modules directory that contains the module. And that’s an aspect where caching the resolved module greatly helps.

But it gets even better! Lots of projects make use of path mapping aliases to save a little bit of typing, so that you can use the same import specifiers everywhere and avoid lots of dots ../../../. This is typically done via TypeScript’s paths compiler option or a resolve alias in a bundler. The problem with that is that these typically are indistinguishable from package imports. If I add a path mapping to the features directory at /Users/marvinh/my-project/src/features/ so that I can use an import declaration like import {...} from “features/DetailPage”, then every tool should know about this.

But what if it doesn’t? Since there is no centralized module resolution package that every JavaScript tool uses, they are multiple competing ones with various levels of features supported. In my case the project makes heavy use of path mappings and it included a linting plugin that wasn’t aware of the path mappings defined in TypeScript’s tsconfig.json. Naturally, it assumed that features/DetailPage was referring to a node module, which led it to do the whole recursive upwards traversal dance in hopes of finding the module. But it never did, so it threw an error.

Caching all the things

Next I enhanced the logging to see how many unique file paths the function was called with and if it always returned the same result. Only about 2.5k calls to isFile had a unique file path and there was a strong 1:1 mapping between the passed file argument and the returned value. It’s still more than the amount of files in the project, but it’s much lower than the total 15k times it was called. What if we added a cache around that to avoid reaching out to the file system?

const cache = new Map();

function resolve(file) {
	const cached = cache.get(file);
	if (cached !== undefined) return cached;

	// ...existing resolution logic here

	const resolved = isFile(file);
	cache.set(file, resolved);
	return file;
}

The addition of a cache sped up the total linting time by another 15%. Not bad! The risky bit about caching though is that they might become stale. There is a point in time where they usually have to be invalidated. Just to be on the safe side I ended up picking a more conservative approach that checks if the cached file still exists. This is not an uncommon thing to happen if you think of tooling often being run in watch mode where it’s expected to cache as much as possible and only invalidate the files that changed.

const cache = new Map();

function resolve(file) {
	const cached = cache.get(file);

	// A bit conservative: Check if the cached file still exists on disk to avoid
	// stale caches in watch mode where a file could be moved or be renamed.
	if (cached !== undefined && isFile(file)) {
		return cached;
	}

	// ...existing resolution logic here
	for (const ext of extensions) {
		const filePath = file + ext;

		if (isFile(filePath)) {
			cache.set(file, filePath);
			return filePath;
		}
	}

	throw new Error(`Could not resolve ${file}`);
}

I was honestly expecting it to nullify the benefits of adding a cache in the first place since we’re reaching to the file system even in the cached scenario. But looking at the numbers this only worsened the total linting time only by 0.05%. That’s a very minor hit in comparison, but shouldn’t the additional file system call matter more?

The file extension guessing game

The thing with modules in JavaScript is that the language didn’t have a module system from the get go. When node.js came onto the scene it popularized the CommonJS module system. That system has several “cute” features like the ability to omit the extension of the file you’re loading. When you write a statement like require("./foo") it will automatically add the .js extension and try to read the file at ./foo.js. If that isn’t present it will check for json file ./foo.json and if that isn’t available either, it will check for an index file at ./foo/index.js.

Effectively we’re dealing with ambiguity here and the tooling has to make sense of what ./foo should resolve to. With that there is a high chance of doing wasted file system calls as there is no way of knowing where to resolve the file to, in advance. Tools literally have to try each combination until they find a match. This is worsened if we look at the total amount of possible extensions that exist today. Tools typically have an array of potential extensions to check for. If you include TypeScript the full list for a typical frontend project at the time of this writing is:

const extensions = [
	".js",
	".jsx",
	".cjs",
	".mjs",
	".ts",
	".tsx",
	".mts",
	".cts",
];

That’s 8 potential extensions to check for. And that’s not all. You essentially have to double that list to account for index files which could resolve to all those extensions too! This means that our tools have no other option, other than looping through the list of extensions until we find one that exists on disk. When we want to resolve ./foo and the actual file is foo.ts, we’d need to check:

foo.js -> doesn’t exist
foo.jsx -> doesn’t exist
foo.cjs -> doesn’t exist
foo.mjs -> doesn’t exist
foo.ts -> bingo!

That’s four unnecessary file system calls. Sure you could change the order of the extensions and put the most common ones in your project at the start of the array. That would increase the chances of the correct extension to be found earlier, but it doesn’t eliminate the problem entirely.

As part of the ES2015 spec a new module system was proposed. All the details weren’t fleshed out in time, but the syntax was. Import statements quickly took over as they have very benefits over CommonJS for tooling. Due to its staticness it opened up the space for lots more tooling enhanced features like most famously tree-shaking where unused modules and or even functions in modules can be easily detected and dropped from the production build. Naturally, everyone jumped on the new import syntax.

There was one problem though: Only the syntax was finalized and not how the actual module loading or resolution should work. To fill that gap, tools re-used the existing semantics from CommonJS. This was good for adoption as porting most code bases only required syntactical changes and these could be automated via codemods. This was a fantastic aspect from an adoption point of view! But that also meant that we inherited the guessing game of which file extension the import specifier should resolve to.

The actual spec for module loading and resolution was finalized years later and it corrected this mistake by making extensions mandatory.

// Invalid ESM, missing extension in import specifier
import { doSomething } from "./foo";

// Valid ESM
import { doSomething } from "./foo.js";

By removing this source of ambiguity and always adding an extension, we’re avoiding an entire class of problems. Tools get way faster too. But it will take time until the ecosystem moves forward on that or if at all, since tools have adapted to deal with the ambiguity.

Where to go from here?

Throughout this whole investigation I was a bit surprised to find that much room for improvement in regards to optimizing module resolution, given that it’s such a central in our tools. The few changes described in this article reduced the linting times by 30%!

The few optimizations we did here are not unique to JavaScript either. Those are the same optimizations that can be found in toolings for other programming languages. When it comes to module resolution the four main takeaways are:

Avoid calling out to the file system as much as possible
Cache as much as you can to avoid calling out to the file system
When you're using fs.stat or fs.statSync always set the throwIfNoEntry: false
Limit upwards traversal as much as possible

The slowness in our tooling wasn’t caused by JavaScript the language, but by things just not being optimized at all. The fragmentation of the JavaScript ecosystem doesn't help either as there isn’t a single standard package for module resolution. Instead, there are multiple and they all share a different subset of features. That’s no surprise though as the list of features to support has grown over the years and there is no single library out there that supports them all at the time of this writing. Having a single library that everyone uses would make solving this problem once and for all for everyone a lot easier.

Speeding up the JavaScript ecosystem - one library at a time

2022-11-29T00:00:00Z

Whilst the trend is seemingly to rewrite every JavaScript build tool in other languages such as Rust or Go, the current JavaScript-based tools could be a lot faster. The build pipeline in a typical frontend project is usually composed of many different tools working together. But the diversification of tools makes it a little harder to spot performance problems for tooling maintainers as they need to know which tools their own ones are frequently used with.

Although JavaScript is certainly slower than Rust or Go from a pure language point of view, the current JavaScript tools could be improved considerably. Sure JavaScript is slower, but it shouldn't be that slow in comparison as it is today. JIT engines are crazy fast these days!

Curiosity lead me down the path of spending some time profiling common JavaScript-based tools to kinda see where all that time was spent. Let's start with PostCSS, a very popular parser and transpiler for anything CSS.

Saving 4.6s in PostCSS

There is a very useful plugin called postcss-custom-properties that adds basic support for CSS Custom Properties in older browsers. Somehow it showed up very prominently in traces with a costly 4.6s being attributed to a single regex that it uses internally. That looked odd.

The regex looks suspiciously like something that searches for a particular comment value to change the plugin's behaviour, similar to the ones from eslint used to disable specific linting rules. It's not mentioned in their README, but a peek into the source code confirmed that assumption.

The place where the regex is created is part of a function that checks if a CSS rule or declaration is preceeded by said comment.

function isBlockIgnored(ruleOrDeclaration) {
	const rule = ruleOrDeclaration.selector
		? ruleOrDeclaration
		: ruleOrDeclaration.parent;

	return /(!\s*)?postcss-custom-properties:\s*off\b/i.test(rule.toString());
}

The rule.toString() call caught my eye pretty quickly. Places where one type is cast to another are usually worth another look if you're tackling performance as not having to do the conversion always saves time. What was interesting in this scenario is that the rule variable always holds an object with a custom toString method. It was never a string to begin with, so we know that we're always paying a bit of serialization cost here to be able to test the regex against. From experience I knew that matching a regex against many short strings is a lot slower than matching it against few long ones. This is a prime candidate waiting to be optimized!

The rather troubling aspect of this code is that every input file has to pay this cost, regardless of whether it has a postcss comment or not. Knowing that running one regex over a long string is cheaper than the repeated regex over short strings and the serialization cost, we can guard this function to avoid even having to call isBlockIgnored if we know that the file doesn't contain any postcss comments.

With the fix applied, the build time went down by a whopping 4.6s!

Optimizing SVG compression speed

Next up is SVGO, a library for compressing SVG files. It's pretty awesome and a staple for projects with lots of SVG icons. The CPU profile reveiled that 3.1s was spent in compressing SVGs though. Can we speed that up?

Searching a bit through the profiling data there was one function that stood out: strongRound. What's more is that function was always followed by a little bit of GC cleanup shortly after (see the small red boxes).

Consider my curiosity piqued! Let's pull up the source on GitHub:

/**
 * Decrease accuracy of floating-point numbers
 * in path data keeping a specified number of decimals.
 * Smart rounds values like 2.3491 to 2.35 instead of 2.349.
 */
function strongRound(data: number[]) {
	for (var i = data.length; i-- > 0; ) {
		if (data[i].toFixed(precision) != data[i]) {
			var rounded = +data[i].toFixed(precision - 1);
			data[i] =
				+Math.abs(rounded - data[i]).toFixed(precision + 1) >= error
					? +data[i].toFixed(precision)
					: rounded;
		}
	}
	return data;
}

Aha, so it's a function that is used to compress numbers, which there are a lot of in any typical SVG file. The function receives an array of numbers and is expected to mutate its entries. Let's take a look at the type of variables that are used in its implementation. With a bit of closer inspection we notice that there is a lot of back and forth casting between string and numbers.

function strongRound(data: number[]) {
	for (var i = data.length; i-- > 0; ) {
		// Comparison between string and number -> string is cast to number
		if (data[i].toFixed(precision) != data[i]) {
			// Creating a string from a number that's casted immediately
			// back to a number
			var rounded = +data[i].toFixed(precision - 1);
			data[i] =
				// Another number that is casted to a string and directly back
				// to a number again
				+Math.abs(rounded - data[i]).toFixed(precision + 1) >= error
					? // This is the same value as in the if-condition before,
					  // just casted to a number again
					  +data[i].toFixed(precision)
					: rounded;
		}
	}
	return data;
}

The act of rounding numbers seems like something that can be done with a little bit of math alone, without having to convert numbers to strings. As a general rule of thumb a good chunk of optimizations are about expressing things in numbers, the main reason being that CPUs are crazy good at working with numbers. With a few changes here and there we can ensure that we always stay in number-land and thus avoid the string casting entirely.

// Does the same as `Number.prototype.toFixed` but without casting
// the return value to a string.
function toFixed(num, precision) {
	const pow = 10 ** precision;
	return Math.round(num * pow) / pow;
}

// Rewritten to get rid of all the string casting and call our own
// toFixed() function instead.
function strongRound(data: number[]) {
	for (let i = data.length; i-- > 0; ) {
		const fixed = toFixed(data[i], precision);
		// Look ma, we can now use a strict equality comparison!
		if (fixed !== data[i]) {
			const rounded = toFixed(data[i], precision - 1);
			data[i] =
				toFixed(Math.abs(rounded - data[i]), precision + 1) >= error
					? fixed // We can now reuse the earlier value here
					: rounded;
		}
	}
	return data;
}

Running the profiling again confirmed that we were able to speed up build times by about 1.4s! I've filed a PR upstream for that too.

Regexes on short strings (part 2)

In close vicinity to strongRound another function looked suspicious as it takes up nearly a whole second (0.9s) to complete.

Similar to stringRound this function compresses numbers too, but with the added trick that we can drop the leading zero if the number has decimals and is smaller than 1 and bigger than -1. So 0.5 can be compressed to .5 and -0.2 to -.2 respectively. In particular the last line looks of interest.

const stringifyNumber = (number: number, precision: number) => {
	// ...snip

	// remove zero whole from decimal number
	return number.toString().replace(/^0\./, ".").replace(/^-0\./, "-.");
};

Here we are converting a number to a string and calling a regex on it. It's extremely likely that the string version of the number will be a short string. And we know that a number can not be both n > 0 && n < 1 and n > -1 && n < 0 at the same time. Not even NaN has that power! From that we can deduce that either only one of the regexes matches or none of them, but never both. At least one of the .replace calls is always wasted.

We can optimize that by differentiating between those cases by hand. Only if we know that we're dealing with a number that has a leading 0 should we apply our replacement logic. Those number checks are quicker than doing a regex search.

const stringifyNumber = (number: number, precision: number) => {
	// ...snip

	// remove zero whole from decimal number
	const strNum = number.toString();
	// Use simple number checks
	if (0 < num && num < 1) {
		return strNum.replace(/^0\./, ".");
	} else if (-1 < num && num < 0) {
		return strNum.replace(/^-0\./, "-.");
	}
	return strNum;
};

We can go one step further and get rid of the regex searches entirely as we know with 100% certainty where the leading 0 is in the string and thus can manipulate the string directly.

const stringifyNumber = (number: number, precision: number) => {
	// ...snip

	// remove zero whole from decimal number
	const strNum = number.toString();
	if (0 < num && num < 1) {
		// Plain string processing is all we need
		return strNum.slice(1);
	} else if (-1 < num && num < 0) {
		// Plain string processing is all we need
		return "-" + strNum.slice(2);
	}
	return strNum;
};

Since there is a separate function to trim the leading 0 in svgo's codebase already, we can leverage that instead. Another 0.9s saved! Upstream PR.

Inline functions, inline caches and recursion

One function called monkeys intrigued me due to its name alone. In traces I could see that it was called multiple times inside itself, which is a strong indicator that some sort of recursion is happening here. It's often used to traverse a tree-like structure. Whenever some sort of traversal is used, there is a likelihood that it's somewhat in the "hot" path of the code. That's not true for every scenario but in my experience it has been a good rule of thumb.

function perItem(data, info, plugin, params, reverse) {
	function monkeys(items) {
		items.children = items.children.filter(function (item) {
			// reverse pass
			if (reverse && item.children) {
				monkeys(item);
			}
			// main filter
			let kept = true;
			if (plugin.active) {
				kept = plugin.fn(item, params, info) !== false;
			}
			// direct pass
			if (!reverse && item.children) {
				monkeys(item);
			}
			return kept;
		});
		return items;
	}
	return monkeys(data);
}

Here we have a function that creates another function inside its body which recalls the inner function again. If I had to guess, I'd assume that this was done here to save some keystrokes by not having to pass around all arguments again. Thing is that functions that are created inside other functions are pretty difficult to optimize when the outer function is called frequently.

function perItem(items, info, plugin, params, reverse) {
	items.children = items.children.filter(function (item) {
		// reverse pass
		if (reverse && item.children) {
			perItem(item, info, plugin, params, reverse);
		}
		// main filter
		let kept = true;
		if (plugin.active) {
			kept = plugin.fn(item, params, info) !== false;
		}
		// direct pass
		if (!reverse && item.children) {
			perItem(item, info, plugin, params, reverse);
		}
		return kept;
	});
	return items;
}

We can get rid of the inner function by always passing all arguments explicitly vs capturing them by closure like before. The impact of this change is rather minor, but in total it saved another 0.8s.

Luckily this is already addressed in the new major 3.0.0 release, but it will take a bit until the ecosystem switches to the new version.

Beware of for...of transpilation

A nearly identical problem occurs in @vanilla-extract/css. The published package ships with the following piece of code:

class ConditionalRuleset {
	getSortedRuleset() {
		//...
		var _loop = function _loop(query, dependents) {
			doSomething();
		};

		for (var [query, dependents] of this.precedenceLookup.entries()) {
			_loop(query, dependents);
		}
		//...
	}
}

What's interesting about this function is that it's not present in the original source code. In the original source it's a standard for...of loop.

class ConditionalRuleset {
	getSortedRuleset() {
		//...
		for (var [query, dependents] of this.precedenceLookup.entries()) {
			doSomething();
		}
		//...
	}
}

I couldn't replicate this issue in babel or typescript's repl, but I can confirm that it's introduced by their build pipeline. Given that it seems to be a shared abstraction over their build tool I'd assume that a few more projects are affected by this. So for now I just patched the package locally inside node_modules and was happy to see that this improved the build times by another 0.9s.

The curious case of semver

With this one I'm not sure if I've configured something wrong. Essentially, the profile showed that the whole babel configuration was always read anew whenever it transpiled a file.

It's a bit hard to see in the screenshot, but one of the functions taking up much time was code from the semver package, the same package that's used in npm's cli. Huh? What has semver to do with babel? It took a while until it dawned on me: It's for parsing the browserlist target for @babel/preset-env. Although the browserlist settings might look pretty short, ultimately they were expanded to about 290 individual targets.

That alone isn't enough for concern, but it's easy to miss the allocation cost when using validation functions. It's a bit spread out in babel's code base, but essentially the versions of the browser targets are converted to semver strings "10" -> "10.0.0" and then validated. Some of those version numbers already match the semver format. These versions and sometimes version ranges are compared against each other until we find the lowest common feature set we need to transpile for. There is nothing wrong with this approach.

Performance problems arise here, because the semver versions are stored as a string instead of the parsed semver data type. This means that every call to semver.valid('1.2.3') will create a new semver instance and immediately destroy it. Same is true when comparing semver versions when using strings: semver.lt('1.2.3', '9.8.7'). And that is why we're seeing semver so prominently in the traces.

By patching that locally in node_modules again, I was able to reduce the build time by another 4.7s.

Conclusion

At this point I stopped looking, but I'd assume that you'll find more of these minor performance issues in popular libraries. Today we mainly looked at some build tools, but UI components or other libraries usually have the same low hanging performance issues.

Will this be enough to match Go's or Rust's performance? Unlikely, but the thing is that the current JavaScript tools could be faster than they are today. And the things we looked at in this post are more or less just the tip of the iceberg.

Continue reading Part 2.

Running 1000 tests in 1s

2022-10-02T00:00:00Z

Recently, I tweeted that the whole test suite for Preact, a modern framework to build web apps, runs in approximately 1s. It's composed of 1003 tests at the time of this writing that run in the browser and assert against the real DOM.

Here is a video of what that looks like:

That tweet struck a nerve, because those numbers aren't even close to be achievable in any of the popular test runners in the frontend space right now. Many newer web developers have never experienced a fast test suite that runs in 1s. Naturally, the question popped up as to what it is that made Preact's test suite so fast.

Establishing a baseline

Before we begin, we should have a rough baseline of how fast it could be in theory. To do that we need to know what kind of tests we want to run. In Preact's case it's mostly about asserting that it rendered the correct output. For that we prefer to test against the real DOM inside one or potentially many browsers to ensure compatibility. The majority of test cases look similar to this:

// Create a DOM container element to render into
const container = document.createElement("div");

// Render `<p>foo</p>` into `<div id="app />`
render(<p>foo</p>, container);

// Check if the rendered HTML is correct.
expect(container.innerHTML).toEqual("<p>foo</p>");

Let's simplify this even further so that we could copy and paste this snippet into the browser. And you know what: We'll flex the browser's muscle a little and run this test 100000 times.

import { render, h } from "https://esm.sh/preact";

console.time();
for (let i = 0; i < 100_000; i++) {
	const container = document.createElement("div");
	render(h("p", null, "foo"), container);

	if (container.innerHTML !== "<p>foo</p>") {
		throw new Error("fail");
	}
}
console.timeEnd();

Result:

On my machine (MacBook Air M1) all 100000 tests complete in about ~182ms. Sure, the test case is a bit simplified and we definitely have a few more complex tests in our suite, but these timings are what we should keep in the back of our minds as a baseline of how fast things could be. Anything that we add to our setup from this point on is merely overhead.

Blast from the past

Those that have been around for a while, know that we the most popular test runners were different back in the day. There was Mocha, Jasmine, tap, tape and many more. What they all had in common was speed. Let's check that for ourselves by adding Mocha to the mix. A few script tags later after hitting refresh we get some a new number:

~210ms

Adding Mocha added about ~35ms of overhead. That's plenty fast for a test runner that has been around since 2011. Jasmine is even older, being published in 2008 and runs similarly quick.

This poses the question: Why are those older test runners so much faster?

Living in an isolated world

The answer to that question is: Test isolation. With the rise of Promises and later async/await, writing asynchronous code became more popular and with that the drive for test runners to invest into test isolation. With every test having their own environment they can reliably ensure that no test interferes with another by mutating globals or other forms of shared state.

// Module has a global variable
let count = 0;

export function increment() {
	count += 1;
	return count;
}
export function decrement() {
	count -= 1;
	return count;
}

And here is how we use that module in our test file:

import { increment, decrement } from "./my-app";

it("increment", () => {
	expect(increment()).toEqual(1);
});

it("decrement", () => {
	// The assertion fails if `count` isn't reset between
	// test runs.
	expect(decrement()).toEqual(-1);
});

Ensuring that developers don't run into this trap can be a good thing. But it comes at a cost: speed. Creating and tearing down environments for each single test takes a lot of time. So much time in fact, that the majority of time in today's test suites is spent on exactly this. Running the tests itself barely shows up when you trace your test runner. It pales in comparison to the overhead of test isolation.

Thing is, most tests don't need that level of isolation. If we have a function that entirely operates on its inputs and doesn't mutate shared state, then any form of isolation is unnecessary. Yet, we run the whole environment creation and tear down cost regardless, because the test runner applies these by default. Let's illustrate that with an example:

// Example code that doesn't rely on shared state at all.
// The function only relies on its inputs.
function add(a, b) {
	return a + b;
}

This simple add() function doesn't need isolation at all. It can be safely called as often as you want, regardless if it's called in a synchronous context or an asynchronous one.

When can visualize the cost of isolating across test runners, by running a simple addition test and measuring their time.

function add(a, b) {
	return a + b;
}

it("should add numbers", () => {
	// We intentionally don't use an assertion library here
	// to avoid tainting timings by that.
	if (add(1, 2) !== 3) {
		throw new Error("fail");
	}
});

Let's run those tests:

We can already see some difference, but let's scale that up to a 100 tests by duplicating the add.test.js test file a hundred times.

Checking if the addition of two numbers is correct for a hundred times takes a full 1.133s in test runner A and just 10ms in runner B. That's about 114x slower than test runner B.

If we think about how many computations modern processors can do per second, even the 10ms result is super slow. But despite that it's still so much faster than test runner A due to not having to constantly create and tear down test environments.

What about the DOM?

For Preact though, we have to write to the DOM which is a form of shared state. Creating and destroying the whole document for every test is immensely expensive, so we want to avoid doing that. Instead we leverage a bit of knowledge about Preact to speed up our tests. Preact, like other frontend frameworks, renders into a single element. So we only need to supply a unique element per test case.

describe("my test suite", () => {
	let container;

	// Runs before every single test case
	beforeEach(() => {
		container = document.createElement("div");
	});

	// Runs after every single test case, regardless if it
	// failed or succeeded.
	afterEach(() => {
		container.remove();
	});

	it("should render", () => {
		render(<p>hello world</p>, container);
		expect(container.innerHTML).toEqual("<p>hello world</p>");
	});

	//...more tests
});

In doing so we set the amount of isolation we need ourselves and avoid spending time unnecessarily setting up isolation containers.

Global state

Some aspects of Preact, like hooks, require a global variable to track the component that's currently being rendered. This is not something unique to Preact's implementation, but rather how the hook API is designed. We could add a way to reset that state similar to how we do with the DOM, but that would introduce a code-path into Preact that's solely for testing purposes. That's something we don't want to do, as we'd rather test Preact in a way that is as close as possible to how it's used by real users.

For the longest time in Preact's history we just dealt with failures caused by global variables not being reset. And to be honest, it was totally fine. It rarely happened and when it did, it pointed to a bug in Preact itself that we would've missed otherwise. Because whenever something fails in Preact when users use it, it should not end up in an invalid state anyway. So essentially by us not adding any form of isolation for global state, we got free testing out of that.

To make debugging a little easier, we added a way to scope globals to a single test file. That way the terminal isn't spammed with hundreds of failing test cases, but rather to only a few. We do this by creating a separate bundle for every single test file. Everyone of them gets their own copy of Preact and everything else.

/tests
  render.test.jsx // <- has their own copy of Preact
	component.test.jsx // <- has their own copy of Preact too

This works because our global variables aren't truly global in the sense that they have to dangle off of the window-object. Instead they're more akin to module scoped variables. So a new instance of the module, creates a new instance of the variable. Creating a unique bundle per test file takes care of that.

Preact's test setup

We achieve this through the amazing bundling speed by esbuild and then cache every bundle that isn't invalidated by file changes during the development process. So whenever you edit a file and hit save, we'll re-generate only the bundles that included that file, ping karma (coordinates the browser) when we're done and karma just reloads the browser.

All this wouldn't be possible without the compilation speed of esbuild. It's basically so fast that it barely makes a difference, if you create one or more bundles. So we happily traded off the slight hit in test run time in favor of a little nicer debugging experience.

Our whole testing stack basically consists of karma as the browser coordinator, esbuild as the bundler and mocha as the test runner. If there's one thing I'd love to replace from that stack it would be karma, because the APIs feel a little dated. But then again I'd happily deal with its oddities, when it allows me to run a 1000 tests in 1s.

Let's make test suites fast

In summary, the problem with applying the maximum possible isolation is that everything becomes painfully slow. Knowing which level of isolation you need is a sure way to speed up any test suite. The defaults the currently popular test runners cover have them all turned on to accommodate the widest range of possible use cases. That's why they are so slow.

Them being so popular also introduces more of a cultural problem. By now we have a generation of developers who have grown up with those tools being the default ones to pick. They don't know that their tests could run faster, because they've never experienced it. As Andrew puts it on twitter:

And they're right. There is nothing novel about our approach or how we set up our test suite. Both karma and mocha have been around for what feels like forever in web development. They are not new. Only esbuild is somewhat newer. But then again the usage of esbuild isn't unique to our stack either.

What's unique to the Preact team though, is that we always go with what the best option is for ourselves and we fill any blind spots in gluing or creating tooling to achieve that. This requires us to be aware of which amount of isolation we need and want from our test suite, and then only applying that. Nothing more, nothing less.

Because one thing is for sure: Working on Preact is way more fun if all tests complete nearly instantaneous, in 1 second.

How to skew benchmarks in your favour

2022-08-01T00:00:00Z

A common rite of passage for every frontend framework is to compare the execution speed with the established players. After all you want to know if your efforts paid off. Where does your framework positions itself on the performance scale? Maybe you want to make this the main selling point of your framework, so benchmarks can be a motivating factor in squeezing just that little bit more speed out of your code. Whatever your motivation is, let me tell you: Benchmarking is hard and has lots of gotchas. A lot things that can introduce bias to a particular solution.

I thought I'd be fun to share all the things everyone of us did wrong with getting credible benchmark results at some point in our career. Benchmarking can be addictive and those numbers pretty deceiving if your not careful. I know, because I've been there. I made the same mistakes as outlined in this post.

Let's dive into how accidental bias is introduced in framework benchmarks.

Outdated versions

You've been working on your framework for quite a while now. You had your benchmark suite since the beginning and have been solely focussed on making your framework the fastest out there. But because you've been at it for so long, the other frameworks released new versions which improve their performance. Unbeknownst to you, you've accidentally introduced a bias in your suite that favours your own solution.

Outdated code

It's not just new framework versions though. With time, programming styles change. Chances are that a framework which has been around for a while has multiple ways of creating - let's say - a component. If you didn't update your benchmark, then you were comparing your solution to the how folks would've written code for the other framework months or even years ago. It's likely that the older style uses more closures, more method calls or something else, which makes it slower than the most recent way to write code for it.

Incorrect results

If you're rolling your own benchmark suite you probably didn't bother to write code that asserts that each run rendered the correct result. Maybe your still evaluating if your approach is worth it and skipped the whole attributes thing because you're more interested in swapping rows. But then it hits you, that the benchmark you've been working with uses attributes like ‘class' to add css classes on every element. So what you've been measuring all this time, has been how quickly your framework renders no attributes versus a framework that does. Oops!

Same is true if your code throws an exception early during a run. Depending on the benchmark runner that you're using, it might not show ‘console.log's or errors. What you've been measuring in this scenario is how quickly your code stopped working. I know, I know. That's a stupid mistake. But no worries, this happens to the best of us!

Batching runs

At this point your framework has matured, you've added all the bells and whistles and now you think to yourself: "Why should my framework render as fast as it can? Isn't it enough if I just render at 30fps or 60fps at best?" You've seen some other player hype this up into space and you don't want to miss out on what the cool kids are doing. So you add scheduling to your framework and limit it to a certain amount of renders to achieve a specific fps limit.

What you didn't think of though, was that you're now batching benchmark runs together. Picture this: If it takes your framework 14ms to do the work than each run would take that amount of time. There might be a little variance here and there but every number of every run should fall into the same ballpark. The benchmark runner will receive something like: 14ms, 15ms, 13ms, 14ms, 14ms, 13ms, etc.

But if your merging runs into one on every fourth invocation, your doing way less work. The benchmark runner now gets numbers looking like: 14ms, 1ms, 0ms, 2ms, 14ms, 0ms, etc. Naturally, the runner will think that your framework was faster. However, it's not. You just fooled yourself. If you're using a decent runner, it will print a warning when the variance is too high between runs.

Accidental overhead

If you didn't go the custom template route for your framework, chances are that that JSX thing was a pretty compelling option. You've added your own createElement function (the thing JSX gets compiled to) to your package and use that in your benchmark. All the other virtual-dom based frameworks provide their own createElement implementation too, so it's fair game, right?

There is one problem though: The babel transform only allows one single JSX transform per file. That's annoying! You don't want to duplicate that section of code for other frameworks as your constantly playing around with different amounts of elements, text nodes or other things.

"No problem!", you think to yourself and create a little function that converts the return value of your createElement calls to whatever the other framework needs.

const vnodes = (
	<div>
		<h1>Hello world!</h1>
	</div>
);

new Benchmark()
	.add("my framework", () => {
		render(vnodes);
	})
	.add("other framework", () => {
		const app = convert(vnodes);
		renderOther(app);
	});

You run the benchmark again and the numbers are amazing! Your framework is miles ahead of everyone else! But wait! Is it really? You go back to your benchmark to verify the numbers. They look too good to be true. Lo and behold, you notice that you call the conversion function during the run for the other framework. So you didn't actually measure how long the framework took to render, but how much the difference between converting the input data (=here vnodes) takes versus not doing that…

Note that this is just one example of adding overhead. There are many more ways to do that for a specific player.

CPU bias

You've been doing this benchmarking thing for a while now and you're pretty satisfied with the results. Your framework repeatedly yields better numbers than the others. During one of your benchmark sessions you comment out your benchmark case, which happens to be the first. You run the benchmark again, but something is odd. Suddenly the numbers for the other framework has improved dramatically! What the…?

Congratulations, you've fallen victim to CPU throttling. You know, because benchmarks are typically very CPU intensive, CPUs need to do a lot of work and get pretty hot. If it gets too hot, it must lower the frequency to cold down and avoid damage.

Problem is that with a lower frequency, it isn't able to do as much work as it did before anymore. For our benchmark this means that our framework ran at full speed, whereas sometime during the other's framework run, the CPU got too hot and throttled down, leading to worse results for the other framework. This is especially common with laptops which don't have space for extensive cooling systems due to their thinness.

JIT and GC

JavaScript being a Just-In-Time compiled language makes benchmarking even harder. You know the engine doesn't know about what your doing in that one file. It just views the whole thing as one big program. If it detects that your code doesn't have side effects and the return value isn't used, it assumes that this piece is dead code and will eliminate that. You essentially, measured how quickly the engine detects that you're doing nothing.

Another common issue are GC (=Garbage Collection) pauses. Because the whole thing is just a program from the engines perspective, the engine determines when it is the best time to do the GC. These heuristics are not deterministic and depend on a lot of other factors of your machine. Depending on when the engine decides to do the GC your benchmark results might vary a lot from run to run.

Conclusion

I hope this post gave you a little bit of insight as to how easy it is to create a benchmark that favours a specific player or introduces bias. There are obviously lots more ways to do that than shown here, so always check how they arrived at those numbers, before trusting the marketing material. If in doubt the benchmark was likely wrong.

But know that this is often not done out of malice. Benchmarking is hard, way harder than it seems! Usually it's just an honest mistake and the developer in question wasn't aware of all the gotchas surrounding it.

Always double check that you're measuring what you think you are measuring!

A look at web components

2020-09-04T00:00:00Z

About a week ago, I spent time looking at web components, specifically how we can ease converting Preact components. One of my friends is playing around with them at work and it seemed like a fun challenge to take on. Personally I've never used web components before that. I just didn't have the chance to work on a project which required them so far. So my understanding of them was formed through word of mouth and the usual hot takes that are shared on twitter. But despite that I was geniously curious about them.

To recap: Our preact-custom-element adapter is a small bridge that can turn any Preact component into a web component via a simple function call:

import register from "preact-custom-element";

const Greeting = props => <p>Hello, {props.name}!</p>;
register(Greeting, "x-greeting", ["name"]);

Why web components?

The main benefit of web components is that you can render them from any other framework as well as in plain HTML. This is useful if you're building a design system and have to support a plethora of other frameworks that need to consume your components. You can literally drop a web component into any framework and have them work out of the box!

Despite sounding great on paper there are some head scratching design choices though. The deeper I dive into them the weirder the API feels to me. For granted as a user of preact-custom-element you'll not notice anything of that and I guess this post is more about my first impressions after using for a while.

Style encapsulation

For years, a lot of thought has been spent battling CSS specificity by scoping CSS to certain areas of a page. Typically this involves prefixing CSS selectors with a unique class name and getting rid of the cascade, so that it is more predictable where the CSS will be applied. The solutions range from CSS-Modules, CSS-in-JS to various compiler-based approaches.

Web components solve that on the platform level. Each custom element can have a so-called shadow DOM, which is a DOM tree that is hidden from the page and only accessible from inside the custom element.

Weirdly this is also web components biggest weakness and biggest blocker to use them. Libraries typically don't support shadow DOM natively (can't blame them), which leaves us in a weird spot. The intended solution seems to point to having a compiler that figures out which component needs what kind of styles and let it insert the sheet at the appropriate place.

Without a compiler the solution is more... err gross. It essentially comes down to copying style sheets from the host page into the shadow DOM and attaching a MutationObserver in case they change.

Attributes and Properties

There is this myth going around web dev circles you can pass only strings to custom elements. This stems from the eternal confusion about the difference between attributes and properties on the web. In a nutshell, attributes describe the HTML notation and properties of the JavaScript API.

<!-- foo is an attribute here, only strings allowed -->
<my-custom-element foo="bar"></my-custom-element>

vs properties

const el = document.createElement("my-custom-element");
el.foo = "bar"; // foo is a property, can be anything

The latter allows you to pass any JS value around, whether it is an object, a function or a value of any other type. Declaring an attribute on the other hand is bound to the semantics of HTML and only supports strings. HTML being the natural authoring format of web components it's very understandable how this myth came to be. Even more so when you consider devs having used other templating languages for years which all support complex data types.

As with anything in our industry any problem can be duct-taped around and workarounds emerged quickly. The most common one seems to be to append a special suffix (-json) to each attribute, that serves as a hint to the adapter that the stringified value needs to be parsed.

<my-custom-element foo-json="[1, 2, 3]"></my-custom-element>

While it solves one of the shortcomings of the authoring experience in HTML, I'm a bit on the fence about it admittedly. To be honest though, I don't know of another good solution to this problem, so I can see us adding this in the near future to our adapter via a JSON.parse.

observedAttributes

To support updating components when consumers call el.setAttribute('foo', 123) instead of doing el.foo = 123 the spec expects us to declare which attributes should trigger the update. It's a static property on the custom element class that is an array of strings.

class MyCustomElement extends HTMLElement {
	static observedAttributes = ["foo"];
}

Without this our custom element will not update if we call el.setAttribute("foo", 123). From an end user's perspective it's an error prone API to have. It requires the user to keep it in sync with the component implementation itself. We currently require this in our adapter too, but I really want to get rid of it to avoid those pitfalls.

So I was curious as to how this API came to be. The only answers I could find lie this GitHub issue. It seems like the main reason was to avoid traveling the C++ to JS bridge all the time. The style attribute in particular is cited as an example of a very costly update. Scouring various native web component libraries on GitHub it seems like nobody does this though.

As expected, devs quickly found workarounds for this and it's mentioned in the same issue. To avoid having to declare the list of observable attributes by hand, we can leverage a MutationObserver that listens for all attribute changes and we can fire our own update function ourselves.

function observeAttrChange(el, callback) {
	var observer = new MutationObserver(mutations => {
		mutations.forEach(mutation => {
			if (mutation.type === "attributes") {
				let newVal = mutation.target.getAttribute(mutation.attributeName);
				callback(mutation.attributeName, newVal);
			}
		});
	});
	observer.observe(el, { attributes: true });
	return observer;
}

It may not be what the spec authors originally had in mind, but solves a real problem, that can otherwise only be solved with a compiler. A compiler would know the properties of a component and can declare the observedAttributes property up-front. As an escape hatch we'll probably only use the MutationObserver approach, if the user didn't set observedAttributes by themselves. Time will tell!

Slots are great!

<slots>-nodes are in spirit similar to what you'd do with 'props.children` in a Preact component. They allow you to place nodes into a specific point in your shadow DOM.

<my-custom-element>
	<span slot="foo">some content</span>
</my-custom-element>

<!-- shadow DOM -->
<div>
	<slot name="foo"><!-- nodes will be placed here --></slot>
</div>

This is a very neat API and I'm impressed how neatly it integrates with HTML. I think the authors did a fantastic job here!

Conclusion

This pretty much sums up my journey into web components so far. It's an interesting aspect of the DOM, albeit being a strange API. Nonetheless, with IE11 finally having an EOL date, it will be interesting to see how it will evolve.

Despite all the controversies, the troubled history, and the rough API, I feel like it's a win for the web. And as usual with Preact we try to support all kinds of use cases as best as we can.

Portals considered harmful

2020-07-18T00:00:00Z

So today I spent a few hours going through various GitHub repos to see how the Portal component in various virtual-dom Frameworks is used (and abused?) in the wild. It's always a fun thing to do for anyone working on frameworks, because users usually discover new ways of how to use features in ways it wasn't intended by the authors. Sometimes something cool comes out of and sometimes so good that the framework will cater to that use case. It's not all just sunshine and roses though because sometimes using features in unintended scenarios may break stuff. This is the story of the Portal component.

To recap: A Portal allows you to jump from the current DOM node to a new container and continue rendering from there. A common use case for that are Modals that we may want to render just before the closing </body>-tag. Another use case are tooltip components that need to be positioned freely.

Let's imagine we have this HTML:

<body>
	<!-- We'll render our app here -->
	<div id="app"></div>
	<!-- Modals should be rendered here -->
	<div id="modals"></div>
</body>

and this accompanying Preact code:

import { render } from "preact";
import { createPortal } from "preact/compat";

const modalContainer = document.getElementById("modals");

function App() {
	return (
		<div>
			Hello
			{createPortal(<div>World!</div>, modalContainer)}
		</div>
	);
}

render(<App />, document.getElementById("app"));

Then the final HTML would look like this:

<body>
	<div id="app">
		<div>Hello</div>
	</div>
	<div id="modals">
		<div>World!</div>
	</div>
</body>

They look nice, feel good to use, but they aren't necessary in most cases.

CSS to the rescue

The modal scenario can be solved without any JavaScript overhead at all. There isn't always a need to take a sledgehammer to crack a nut. Some things can be done with just a tiny bit of CSS:

.my-modal {
	position: fixed;
	z-index: 200;
}

With positon: fixed we're creating a new stacking context here and can leverage an additional z-index property to position the modal above the current visible DOM. This works extremely well! A similar thing can be done for tooltips when they are anchored into the target element's container.

.container {
	/* Create new stacking context */
	position: relative;
}

.tooltip {
	/* position tooltip absolute inside container */
	position: absolute;
	top: 100%;
	left: 50%;
	transform: translateX(-50%);
}

But with most things web-related there are exceptions to this and the most common one that's referenced is that you have a parent with overflow: hidden and you need to break out of that container. Fair bit of warning: Before you do any of that, think twice if you really need Portals or if you can make you're life easier with having a proper CSS hierarchy.

So in those rare cases where Portals are a requirement they do wonders! It's a good tool to have in ones toolbelt, albeit it should be used wisely and with caution.

Why Portals are dangerous

Problems arise when they're used in ways they weren't intended to be used for. Take the following snippet as an example of that:

const root = document.getElementById("root");

const App = () => {
	return (
		<div>
			foo
			{createPortal("bar", root)}
			{createPortal("baz", root)}
		</div>
	);
};

render(<App />, root);

Here we have a Preact application that renders into <div id="root"></div>. So far so good, but now it gets weird: We try to render the word "bar" into the same container as App and while we're at it, let's take the biscuit by rendering into the same container again, via a second Portal! In the end we have have three virtual-dom trees battleing for the same DOM container. And it gets worse: The expected outcome of that is not <div>foo bar baz</div> (spaces added for readability), but instead it is <div>bar baz foo</div>.

Interestingly, every framework renders this a little different:

Framework A: <div>bar baz foo</div>
Framework B: <div>bar foo baz</div>
Framework C: <div>baz</div>

Even though everyone's result is different, everyone is correct at the same time. We can't fault any of them. So what's happening here? If you put yourself into the shoes of a framework what would you do? Should the framework remove existing DOM? Should it render before or after the existing child nodes?

Framework A

Framework A renders Portals before the App component is appened to the DOM. It's basically bottom-to-top rendering. We can deduce from the insertion order that this framework has a special branch for dealing with Portals inside an existing tree. Otherwise we'd observe a behavior similar to Framework B where Portals are treated the same way as roots created by render().

// 1st Portal
<div id="root">
  bar
</div>

// 2nd Portal
<div id="root">
  bar
  baz
</div>

// App root
<div id="root">
  bar
  baz
  <div>foo</div>
</div>

Framework B

Framework B tries work around any nodes that are already present in the tree. First the App will be rendered and both Portals take their turn only after App is finished. It looks like there is no special branching for Portals and that it shares the underlying semantics with render().

This means that the reconciler is aware of any existing nodes and when it inserts the Portals it tries its best to move the nodes around the original content. Whilst this logic is not ideal for Portals, it is advantageous for scenarios where Browser extensions like Google Translate which may insert random DOM nodes into our tree.

// App
<div id="root">
  <div>foo</div>
</div>

// 1st Portal
<div id="root">
  bar
  <div>foo</div>
</div>

// 2nd Portal
<div id="root">
  bar
  <div>foo</div>
  baz
</div>

Framework C

Our last, but arguable the most elegant contender Framework C makes short work of the situation. It simply renders over the existing DOM, thereby removing any child nodes that were present at that time. It's simple, the code is much more elegant and the outcome is predictable. There is no additonal ordering/inserting logic needed. It's kinda the ultimate zen for developers working on frameworks.

// App
<div id="root">
  <div>foo</div>
</div>

// 1st Portal
<div id="root">
  bar
</div>

// 2nd Portal
<div id="root">
  baz
</div>

Err... what about updates?

If you think the above scenario was already tough (it is) and you might be wondering what else is out there, then let me take you right to the endboss of Portals: Rendering literally into each others tree.

function App(props) {
	const [i, update] = useState(0);
	const ref = useRef();
	return (
		<div ref={ref}>
			foo
			{createPortal("bar", root)}
			{createPortal("baz", i % 2 === 0 ? root : ref.current)}
			<button onClick={() => update(i + 1)}>click</button>
		</div>
	);
}

render(<App />, root);

At this point we're even deeper in undefined behavior territory. Nobody truly knows what the expected result should be here all frameworks lead to inconsistent results. We can observe the first render and then the second one which changes the order. But starting from there we will never be able to have the same result that we had with our first render. Every render after the first will stay the same. Pretty weird, but to be expected for undefined behavior.

// 1st render
<div id="root">
  <div>
    bar
    baz
    foo
    <button>click</button>
  </div>
</div>

// 2nd render
<div id="root">
  <div>
    bar
    baz
    <button>click</button>
    foo
  </div>
</div>

// 3rd render
<div id="root">
  <div>
    bar
    baz
    <button>click</button>
    foo
  </div>
</div>

// 4th render is the same as 3rd

Ultimatively, this is perfectly fine! This was never an intended use case for Portals. At this point all bets are off and the code depends on multiple features being just right for this scenario. The code depends on the Portal component (obviously), on root detection, stable DOM ordering, unrelated child DOM node detection, etc. The list goes on. On top of that any change in the reconciler has the potential to break that code. It's brittle and we should make our code more resilient.

How to use Portals safely

We've spoken in-depth about undefined behavior surrounding Portals, but what's the right and intended way to use them? It all comes down to ensuring that each root has it's own DOM node. A root created by render() shouldn't have to share it's container with other Portals and Portals shouldn't have to share them either. And those nodes should be created outside of the framework to ensure that it isn't suddenly removed whilst the Portal tries to re-render into it. That would be like pulling the rug out from under ones feet.

Which brings us to the snippet from the beginning which is coincedentally the one that's usually featured in the documentation of those frameworks.

// HTML:
// <body>
//   <div id="app" />
//   <div id="modals> />
// </body>

const modals = document.getElementById("modals");
const root = document.getElementById("app");

function App() {
	return (
		<div>
			Hello
			{createPortal(<div>World!</div>, modals)}
		</div>
	);
}

render(<App />, root);

Every Portal, every render() has it's own DOM node. Nobody renders into each other and no roots have to be shared. It's a good and peacful world. A world that brings us framework developers joy again!

Stencil Store Challenge

2020-04-05T00:00:00Z

When Manu from the Stencil team pinged me on Twitter regarding a code golfing challenge, I just couldn't resist! So I thought this could be a good exercise to apply techniques we use while working on Preact to a codebase that's foreign to me.

Getting ready

After the usual git clone and npm install we're good to go. Before we dive in immediately, we should get ourself familar with the overall goal the code is trying to clear. From the looks of it we're dealing with an extension to the Stencil framework which attempts to make state management easier. For that they rely on smaller stores where each property can be observed. This library holds the cold for that.s

Overall I'm getting a Svelte vibe here as they have a similar concept in their frameworks. I expect more frameworks follow in the coming months, but only time will tell for sure. The codebase is authored in TypeScript which is a godsend whenever you have to get familiar with foreign code!

Readability

The first things I usually do is to remove anything that's just noise. In particular with TypeScript, developers tend to write overly verbose type declarations, even though TypeScript can infer most of the types automatically. One of such instances can be seen in the implementation for a Map-like data structure, that's observable:

const use = (...subscriptions: StoreSubscriptionObject<T>[]): void =>
  subscriptions.forEach((subscription: StoreSubscriptionObject<T>): void => {
    //...
  });
};

Luckily for us TypeScript is smart enough to unwrap boxed types like arrays, whenever we iterate over it. We can just drop the verbose type name here. The return type is also not needed as the whole function doesn't make use of the return keyword. Let's drop that too! Since the whole code in this repo is pretty small we don't have to go all enterprise with our naming convention and can shorten StoreSubscriptionObject to just Subscription.

const use = (...subscriptions: Subscription<T>[]) =>
  subscriptions.forEach(subscription => {
    //...
  });
};

Much better! Readabilty is the very foundation to write shorter code. It sets the stage in writing style in which any new code usualy adheres to. This process rarely happens concious, but rather in our unconciesness, because for us humans it's natural to want to fit into the group. If the writing style favors verbosity it makes it harder (at least for me) to quickly scan code and immediately know what it does. Information densitiy is key here! But don't overdo it!

Note: There are many whacky eslint presets for TypeScript out there that force you to manually declare every single type. This is pretty bonkers and completely ignores a huge strength of a mature type system.

Let the golf begin!

Looking at the whole function body, we notice a list of if-statements, that just beg to be optimized.

const use = (...subscriptions: Subscription<T>[]) =>
	subscriptions.forEach(subscription => {
		if (subscription.set) {
			on("set", subscription.set);
		}
		if (subscription.get) {
			on("get", subscription.get);
		}
		if (subscription.reset) {
			on("reset", subscription.reset);
		}
	});

If we check the type declaration of Subscription (formely StoreSubscriptionObject), we can see that this function checks for all possible properties and adds a listener to them. Armed with that knowledge we can rewrite the code to iterate over all properties and assign a listener automatically:

const use = (...subscriptions: Subscription<T>[]) =>
	subscriptions.forEach(subscription => {
		Object.keys(subscription).forEach(key => on(key, subscription[key]));
	});

Although the rewritten function is much shorter I'm not really satisfied with it, as it introduces an iteration in a section which is potentially executed quite a lot. Maybe we can change the way subscriptions are handled itself. The current way relies on each event calling a separate function: One for "set", one for "get" and another one for "reset". When it comes to code-golfing function declarations tend to be on the expensive side, same as strings. So maybe, if we manage to it right, we can kill two birds with one stone.

We're dealing only with a single Subscription type here which is closely tied to a Map.

export interface Subscription<StoreType> {
	get?<KeyFromStoreType extends keyof StoreType>(key: KeyFromStoreType): void;
	set?<KeyFromStoreType extends keyof StoreType>(
		key: KeyFromStoreType,
		newValue: StoreType[KeyFromStoreType],
		oldValue: StoreType[KeyFromStoreType]
	): void;
	reset?(): void;
}

Even though all properties are declared as optional, they're always used together in the code that's provided. There is not a single place where only one of those is used. So how are subscriptions defined? Looking at the internals of ObservableMap we see 3 separate arrays for each event. This is a good thing as a shared object structure would likely lead to more allocations.

const setListeners: SetEventHandler<T>[] = [];
const getListeners: GetEventHandler<T>[] = [];
const resetListeners: ResetEventHandler[] = [];

// The `on()` function is used to create subscriptions
const on: OnHandler<T> = (eventName, callback) => {
	let listeners: any[];
	if (eventName === "set") {
		listeners = setListeners;
	} else if (eventName === "get") {
		listeners = getListeners;
	} else if (eventName === "reset") {
		listeners = resetListeners;
	} else if (Build.isDev) {
		throw new Error("Unknown event " + eventName);
	}
	listeners.push(callback);
};

To set up subscriptions the on(event, callback) function is used. Looking at the function body we find another long if block that doesn't bring us joy. The number of possible events is finite and limited to 3, so we could leverage a similar trick like the one we applied earlier to get rid of the if-statement. We can even remove the error message as the browser's native one is pretty similar when dealing with missing object keys.

const handlers: Handlers<T> = {
	get: [],
	set: [],
	reset: [],
};

const on: OnHandler<T> = (eventName, callback) => {
	handlers[eventName].push(callback);
};

This brings us much more joy! So far we've only dealt with more "cosmetic" code changes. To be able to really unify the subscription process we have to be a bit more agressive and make changes to the user facing API. This requires more knowledge about how this library is actually used, but I'm not familiar enough with Stencil to make that call. Without that optimzation usually tends to break features.

That's it for now

There are probably more areas we can improve on, but I think I've spent enough time here. I did conciously not go into optimizations which would save a byte here and there, because the library seems to be newer and in heavy development. ASome potential avenues that immediately come to mind:

Inline every function that is only used once. This needs to be backed up with numbers, but in general fewer functions compress better with terser+gzip. This is not always the case though, so one should really measure the impact.
Refactor on(event, callback) to on(callback) and pass the event type as the first argument. This obviously breaks the existing API and pushes the check which event we're dealing with to the consumer. It would also shift the performance characteristics, so be careful here! On the plus side we could essentially delete a lot of subscription handling logic, so it's definitely a tradeoff to make.

Conclusion

Hope this short adventure helped to portray the thinking process of what it's like to work on Preact. The main takeaways for me from working on Preact are to really understand what the code in front of you is trying to accomplish and to be aware of the context it is used in. Combine that with a laser sharp focus on readabilty and you have the perfect foundation for writing clear and concise code in your heart.

State of Preact Devtools #2

2019-09-29T00:00:00Z

A little bit of time has past since the announcement that we are working on our very own devtools extension. A lot has happend since then and I'd love to share some news about what's happening behind the scenes. The good news: I'd consider the current code feature-complete and the next will be the polishing phase. It's safe to say that things are progressing nicely without any hiccups.

Screenshot of the current state of the extension.

The main star of the show is obviously the element viewer itself. Having a way to peek at the component tree is incredibly helpful to understand how the screen was rendered. On the surface sucha a tree-view seems easy enough to write down, but when I compared all the devtools from other frameworks and browsers I noticed lots of UX differences, which in my opinion can really make (or break) the usefulness of the devtools.

Pressing the right arrow key here should uncollapse the tree and move the selection to the first child.

Personally, the arrow keys get a lot of usage on my machine. I'm using them as one of the main ways to navigate around and collapse/hide component trees. It's suprising to me that this is sometimes overlooked or has issues like only moving one position when holding down an arrow key. Even if the keyboard navigation is present, one has to make sure that the viewport follows the currently selected item. Otherwise it would move out of sight, hidden behind some scrollbars.

In the end I personally liked the UX of the react-devtools extension the most. It's no secret that Brian Vaughn and the other members of the React team have done an outstanding job there. This is something that I always tried to keep in mind when writing the devtools extension for Preact, because I know a lot of in my area who frequently switch between Preact and React projects. Deviating too much there would ailenate their workflow and cause unnecessary friction for our users. It some minor differences though, which we'll go on in detail later.

Filtering for a less cluttered view

The component tree can get quite long, especially when a css-in-js library is used which creates an additional component for every styled DOM node. This often leads to cluttered component trees, making it hard to see the ones that matter. It's another feature I frequently make use of when jumping between projects and I tried to change the UX a little to better reflect the quick need of changing some filters.

Instead of opening them in a dedicated modal, they'll open in a simple popover without hiding the tree view. The built-in filters to hide Fragments or DOM nodes are always present, so that you can easily toggle them on or off. Note that if you uncheck the Fragment filter, you'll always see a Fragment at the top of the tree. This is because we're re-using Fragments as root nodes in Preact.

The new filter popup where you can quickly hide specific components. Don't mind the visual glitch with the focus ring. This will be fixed.

Clicking on the Add filter button will add a new one, where you can enter a partial component name, that should be hidden. It will directly focus the text input field, which is another little UX detail that makes a difference in day-to-day usage.

Searching for a specific component

When you're implementing filtering into something you'll probably will want to add it's cousin - the search - too! There are always times where you need to find specific components and see their hierachical relation in the tree to other components. The search feature does exactly that and works very similar to the native ctrl + f / cmd + f feature found in all browsers.

But I also made sure pay particular attention to the same little UX features like with the tree view. In this case just pressing Enter will highlight the next search result and pressing Shift + Enter will do the opposite. The latter is often forgotten in different implementations.

Full on props modifications encouraged

Equally important as the tree view is the sidebar panel where props, state, context and later hooks (upcoming feature) can be inspected and modified at-will. For me this aspect of the web has always been the most exciting. We can modify pretty much anything we want and can see the results immedialely. I do think a tight feedback loop makes a world of difference during development.

For this reason I was blown away when I came across this PR in the react repo, that allows more freedom when editing values. You know the old devtools where always a bit lacking in that regard, because you could only modify "primitve" values like booleans, strings, numbers, etc, but never arrays or objects. On top of that there wasn't any way to interactively add new props like you can when adding CSS properties in the native HTML elements panel.

Changes are immediately reflected in your app and you can even undo them in case you they turned out to be wrong.

In short I fell in love and it became a thing I absolutely wanted to enjoy in the devtools for Preact. Two days later the code got committed and thanks to the excellent json5 library the input for complex objects was pretty easy to do. It publish an fork which supports the ES modules syntax (json5-es) until the PR is merged in case you're interested.

Component Holmes Inspector

In the scenario that you know what component rendered a specific element on the page, you can use the neat inspect button which allows you to just click on the element on the page and it will automatically highlight the correct node in the tree view.

Inspecting the devtools with devtools... That's meta!

This again may seem like a simple feature, but quickly gets more complex once you add fitlering to the mix. Because what happens when the inspected element is filtered away? The solution is to just walk upwards until you find a non-filtered parent. It's doable, no doubt and no complains here, but it's another thing to be mindful of when adding such a feature. The same is true for collapsed subtrees. There you need to uncollapse them as you go.

What's next

Now that I feel confident to have a solid feature-set for an inital release, I'll spent the next available time slots on polishing all the things. There are still some obvious bugs here and there which need to be shaken out. The polishing phase is not to be underestimated from a planning perspective, but there aren't any blockers there. It just takes a bit of time.

After that there are many features that I have set my sights on. One of them is hooks state which I have skipped so far, because it needs some modifications to preact/hooks before this can work. I still feel like I haven't found the right way™️ to go about it yet. I'm also very interested to get some sort of highlight-updates added as it was feature I really loved and used a ton in the past. We'll see, time will tell ;)

I'm not sure how much time I'll be able to dedicate to that during October, as I'll be touring around on various conferences and Meetups. One is the frehsly baked localhost.engineering conference in Düsseldorf, Germany and the other one is scriptconf which will be held in Linz, Austria. If you share, be sure to hit me up for chat. And I'll bring a good bunch of stickers with me in case you fancy those ;)

State of Preact Devtools

2019-09-04T00:00:00Z

As many of you know the react team released a revamped devtools extension recently. The improvements are countless and not just for endusers, but also the protocol has changed substaintially for the better. Whereas the previous iteration always asked for the information of the complete tree and every detail at once, the new version follows more a pull based approach. It only requests the data it needs and only when it's needed. That's a stark contrast!

Another neat change is that the mappings for elements now happens on the consumer side. When you're attaching devtools to a virtual-DOM-based framework you need to notify the extension of every change in the tree or duplicate some of the reconciliation when element order changes. Both approaches are valid, but whatever you choose, you need to have a way to match old and new elements. You need to know that the just rendered element matches exactly a node on the other side.

The previous version of react-devtools was great for its time, but known to be a little slow.

With the previous adapter we had to pretend to actually be React, which isn't always easy. With the new one we could now just write our own and attach it to the extension. I started on that adventure in April and got my first components to show up in the new extension (note that it was still marked as experimental back then and months away from a release).

Armed with new possibilities we could do the mapping ourselves in our own preact adapter. Typically you'll store a Map somewhere where you assign an ID for each node. That way you can easily track parent relationships and ordering without having to care about framework specific details. On the plus side this makes the extension code much easier to reason about.

A few weeks later I was able to finally crack it. I got the whole tree showing up in the extension! One by one I spent the following months ticking of one box after another. One week I managed to get props to show up, the other week state and I really made lots of progress.

Not to say that I didn't have my moments where I was stuck on something, but in the end it worked out. Our own demo app we use to test real world code with, was crucial here in aiding my plans.

The difficult bridge to react-devtools

Problems started to arise once the new devtools was released and we received a wider audience of users eager to test it out with Preact. Whilst some issues could be fixed, others could not. I spent 4 full days trying to make it work and ultimately had to call in the defeat.

The new react-devtools extension with Preact. As you can see the props panel is broken.

The reason it's difficult is that under the hood Preact and React do things quite a bit different from each other. Due to the focus on concurrent rendering, React splits everything into so called commits. It describes all the changes that were made in the current render request (for a lack of a better word). This means that each call to setState/forceUpdate or the toplevel render() function will create such a commit.

Those commits are then queued up into a message the devtools understands. Those events will be automatically in order so you can traverse it linearly on the extension side. That's pretty great for performance!

Trouble is that in Preact we don't have such a strict model of commits (yet?). When you call forceUpdate on a component we pause the current render and execute the new one in-between before continuing with the previous one. This obviously breaks the strict ordering rules of events for the devtools.

Note that this is just one of the issues I was facing, there are many more subtle ones, simply because both frameworks work so differently. That's even more true for Preact 8.x which is a whole different beast. Overall the main thing that broke me is the insane amount of time I spent on the adapter that masks Preact as React. I've come to the conclusion that it's better for us in the longterm when we have our own extension.

I want to be clear here that the react-devtools extension (as the name implies) is only targeted at React. We were fully aware that we didn't get any official support for that and for good reason (obviously). The devtools are excellent and some of the best we've seen. They even added tiny features just for us to make it easier to interface with it. We're super grateful for that and we have a lot to thank them for!

It's not you, it's me

I'm fully aware that the current situation where the devtools are kinda broken sucks. And I hate that. It makes me sad because we nearly got it working and I personally see any form of devtools as a huge asset for any framework.

Faced with a hard decision, I went with giving our own extension a go. I've spent the past 2.5 weeks working on that and a prototype is finally coming together. For now my main focus is on getting the elements panel right. Additional features such as some sort of profiling tool will come later.

Don't mind the minor visual glitches (heavy work in progress). I'm more focused on getting the features stable and robust first. It supports both light and dark mode if you're curious.

Introducing Preact Devtools

In just a little more than 2 weeks the basic features are already there. The extension will display a colored icon when it detects Preact on the current page. It will display the current mounted component tree (update and unmount still needs work). It can inspect props and change them. It can highlight the current node in the viewport and most importantely: It's a lot easier for us to work with.

Light version of the Devtools (heavy work in progress).

But it will also take time, more than I'd like it too. Yet I feel like this is the right direction to take. Although I know the react-devtools code like the back of my hand, I was able to add more features in the past two weeks than I was able to in the past months.

Having our own devtools also means that we can explore more Preact related aspects like visualizing other types of data related to components in the tree. This opens a lot of doors for us!

Right now it's in a rough state and I'm confident that it will mature in the next weeks. It's way too early to set on a release (or pre-release) date, but I just wanted to share with you the current state of devtools, so that you all know what's happening.

Hooks vs Classes a few months later

2019-06-13T00:00:00Z

It's been a while now that the hooks concept took over the frontend world by storm. Originally researched by the very talented React team it solves some longstanding issues surrounding the best way to make behaviours easily composable and shareable. A lot has been written about what they are and how to use them, so I won't repeat that here. Instead I'd love to share the maintainers perspective on them.

Once we announced our first Preact X alpha many users immediately jumped on the hooks bandwaggon, and for good reasons! Since that release we've received significant less bug reports and support questions on slack regarding the use of components. With hooks there simply aren't many possiblities to tread down the wrong path anymore. It's a solid API that in my experience is even easier to understand for newcomers, which is always a plus!

So what are the footguns users run into with the Class-API you ask? For that I collected some of the more frequent snippets we received in the last months.

Initializing state is confusing

This is something that trips up people coming from different languages a lot. You know in most OOP-based programming languages there is the concept of setters. It's arguably less common in the JavaScript world, but one can still find it from time to time.

The idea is that you don't modify property directly and instead opt to set them using special setter functions. This allows the underlying class to change/rename the variables under the hood, without the fear of breaking userland code. Because of that you never set the properties directly and the natural conclusion would be to write something like this to initialize the state of a component:

class Foo extends Component {
	constructor(props) {
		super(props);

		// Don't do this.
		this.setState({
			foo: 20,
		});
	}
}

Thing is that this is effectively a no-op. It doesn't initialize the state. Instead we deviate from the common getter/setter concept and set it directly:

class Foo extends Component {
	constructor(props) {
		super(props);

		this.state = {
			foo: 20,
		};
	}
}

This is, again, another think we have to consciously keep in mind. It's something newcomers seem to run into once in a while. With hooks we can sidestep that completely, because they're just a function call. We just pass the initial state upon calling it:

function Foo() {
	const [foo, setFoo] = useState(20);
	//...snip
}

Nested `setState` calls

After pondering about a use case for a while, I still have no idea where one would want to use nested setState calls. A while ago we received a bug report that had code similar to this:

// Don't do this
this.setState({ foo: 3 }, () => {
	this.setState({ bar: 10 }, () => {
		this.setState({ bob: 20 }, () => {
			//...
		});
	});
});

The second argument of the setState function is a callback that will be called when the state is updated. It's super rare in the real-world, and I personally think this is in hindsight a mistake. This pattern is bad for performance, because now you're rendering the component 3 times instead of once.

So what is this code trying to do? What makes it so important to differentiate the second from the third render? If you know a valid use case, please message me. I'd love to know more!

Lifecycles were a bit messy

One tricky thing with the old lifecycle API was the way they were called. Imagine a scenario where you want to execute something whenever your component is mounted or updates. Like a tooltip where you need to position it yourself via JS to know if there is enough space to show it above a button. Otherwise the tooltip should be moved below the button. It's a super common thing but back than we had to split it up into componentDidMount and componentDidUpdate. Naturally the pattern that emerged there was that both cDM and cDU lifecycle hooks just called another method.

class Tooltip extends Component {
	componentDidMount() {
		this.measurePosition();
	}

	componentDidUpdate() {
		this.measurePosition();
	}

	measurePosition() {
		// do some measurements
	}
}

Now compare the above to the hooks version:

function Tooltip() {
	useEffect(() => {
		// do measurements here
	});
}

But the real trouble happens behind the scenes. To successfully support class-based Lifecycles we have to be extremely careful with the arguments. We have to always drag the previous props and state around and be super careful when calling lifecycles that can change them like getDerivedStateFromProps.

The question that pops to mind is: "Why do we even have to do that?" And the reason is that both props and state are reference bound. When we update one of them we set this.props or this.state to the new value and thus losing the reference to previous one. To prevent that we store it the previous version in a variable just before updating it.

// Pseudo code, we don't assign `this.state` synchronously
class Component {
	setState(state) {
		this.prevState = this.state;
		this.state = state;
		enqueueRender(this);
	}
}

// later during render
let inst = MyComponentInstance;
inst.shouldComponentUpdate(inst.nextProps, inst.nextState);

Again, in hooks-land this becomes a lot easier because we can use plain JS to take advantage of closures. We don't need to store the new state immediately on our component instance and can defer that to when the component has completed the diffing phase. That's another case where we can save a few bytes!

Less footguns = less maintenance

At this point one can argue that we could at more checks in preact/debug or create a linter preset to warn about common misuses of the Class-API. Have no doubt, this would work and help our users a lot. But there is a hidden cost for us as maintainers in that we have to write code especially for debugging purposes. On top of that it's another thing that needs to be documented, throughouly tested and so on...

Instead it's much more desireable for us to have a solid API which doesn't allow these issues to pop up in the first place. With something like that we can save us a lot of work, that we can use to work on nextgen features.

Are hooks the perfect API? I don't think so, but it's one of thos that has gotten us the closest so far. It definitely frees us maintainers a lot of time spent answering questions. I'm excited to see where the future will lead us, even more so that more frameworks are much more willing to experiment with new APIs than just a few years before.

Applying Preact minification tricks to CSS

2019-04-15T00:00:00Z

One thing we're known for over at Preact is making code a lot smaller than it originally was. In fact the tiny size is one of the main strengths of Preact. A few days ago a friend of mine Jan Willem Henckel shared a link to CSSBattle, where users can compete against each other in trying to replicate an image with just CSS and HTML. The kicker? You have to use as few characters as possible to get the most points! Currently he holds the top spot with a mere 56 characters for rendering the following page:

It's a greenish rectangle inside a brown canvas. Not the prettiest for sure, but enough to get us going. Intrigued and always up for a code challenge, I gave it a go. Although I mainly write JavaScript or TypeScript these days I was curious to see how much of the knowledge gained from working on Preact can be applied to other areas. The mindset for minifying and optimizing code in general should be very similar in theory, but we're dealing with a different language. Some of the optimization tricks from JS obviously won't transfer to that.

The challenge starts with the following code snippet for the image above:

<div></div>
<style>
	div {
		width: 100px;
		height: 100px;
		background: #dd6b4d;
	}
</style>

As we can see it's just a single div and a style element that holds the CSS. All in all this snippet comes in at 105 characters which is close to twice as much as our target. Here we notice that we have a few repeating strings. The word div is used three times and style occurs twice. Unfortunately, the challenge is measured in characters and not in bytes. If would be the latter we could leverage the famous gzip algorithm to compress the final output like we do with Preact.

Minification tricks that work everywhere

The first obvious optimization we can do is to get rid of unnecessary whitespace and reduce it to one line:

<div></div><style>div{width:100px;height:100px;background:#dd6b4d;}</style>

In the real world this is typically handled automatically by build-tools as the last step in the asset pipeline. That's a good thing, because the above snippet is a lot harder to read than the multiline version. With just this we're down to 75 characters, but we can do a lot more. Since pretty much the dawn of time HTML has supported the style-attribute on elements that can be used to apply CSS inline. This helps us to remove both the opening and closing <style> tag all together. Even better: It also allows us to remove the selector portion of the CSS 🎉

<div style="width:100px;height:100px;background:#dd6b4d"></div>

This lands us at 63 characters, but if we compare our result it looks nothing like the image we're trying to render:

We still need to change the colors and reposition the rectangle. So how can we do that? We don't want to add a second element as they are quite costly in terms of characters. That's when I remembered the single div challenge from a few years back which challenged web developers and designers around the world to make the most out of a single <div>. That was when the industry collectively discovered that we can use (abuse?) the box-shadow-property to create multiple shapes at once.

To do that we need to remove the height and width declaration to make our div spread over the whole canvas. Remember that a div is a block-element! In exchange I tried to position the inner rectangle with a few em values and applied the correct color codes.

<div style="box-shadow:-24em 0 0 12em#b5e0ba,0 0 0 19em#5d3a3a"></div>

We have gotten a little bigger with this version at 70 characters, but our result now looks exactly like our target image.

Coloring strategies

Looking at Jan's score we can see that it's possible to reduce our snippet by 14 more characters. Maybe we can save something by finding more optimal color codes. As most of you know there are various ways to simplify the hexadecimal string. CSS allows you to turn #ffaacc into #fac allowing us to save 3 characters. Sometimes the color code is even shorter than the hex string as it is the case with gray versus #c0c0c0.

Comparing the expected color values with the CSS spec unfortunately doesn't leave us with any reductions. The color codes are unique and can't be compressed. But we're now defeated yet, there are still various avenues we can explore 🍀.

One of those is a feature that was introduced with HTML5, which allows you to remove the quotes around an attribute. Our value needs whitespace in it, but it turns out that we can substitute the space character with a plus and save the two quoting letters.

<div style=box-shadow:-24em+0+0+12em#b5e0ba,0+0+0+19em#5d3a3a></div>

At this point I was wondering whether there are any other length units that are bigger than em. Jan gave me a hint about this before starting this challenge so it should work out. Looking at all the available units in CSS it seems like in for inches fits the bill.

<div style=box-shadow:-4in+0+0+2in#b5e0ba,0+0+0+4in#5d3a3a></div>

After converting the unit to inches we reached 65 characters which is better but nowhere close to 56. What else can we do? Remember when we established that we need a block-level element to span over the whole canvas? Maybe there is another one that has a shorter name. Reading through both MDN and the HTML-Spec I came across this list of all elements that are considered to be block-level. We had the right right nose for it here, because luckily for us the <p>-tag is also part of the list!

Armed with our new findings we can swap out our div for a simple p element.

<p style=box-shadow:-4in+0+0+2in#b5e0ba,0+0+0+4in#5d3a3a></p>

Quirksmode is back from the dead

Only 5 more characters to go! So let's do something that you should never do outside of code golfing challenges: Reduce the code by making it invalid HTML but let it still parse correctly. Let me repeat that: Don't do this in any project! Those of us who've been around a bit longer remember the times when cross-browser compatibility was not so great and to be frank quite lacking. During those dark times of the web it was quite common for web pages to serve invalid HTML 🤷

This is troubling for the browser because now it only has two options on how to proceed:

Bail out of rendering (bad, white page)
Try to render it anyway and guess what the developer meant

The first option is a no go, because users never assume that the page itself is at fault. When something works in one browser and not the other the usual conclusion is that the browser is broken. And how should they know that the page is actually causing issues? That burden lies on us developers to make sure we serve valid HTML.

To combat this browser have implemented a "quirksmode" in which the browser tries to guess what the correct result should be. Depending on the browser that is used this can lead to quite unpredictable results, but in our case, and only because it's a code-golfing challenge, we can get away with it as long as the rendered result stays the same.

What is this unholyness you ask? Well, we can remove the closing </p>-tag 😬:

<p style=box-shadow:-4in+0+0+2in#b5e0ba,0+0+0+4in#5d3a3a>

We're now at 57 characters which is just one more than Jan's high score.

I tried finding a way to remove the last character but after trying for longer than I should, I haven't found a way to do so. Nonetheless I'm happy with the result. We effectively reduced the character count by half which is solid!

Conclusion

Even though CSS and HTML is quite different from JavaScript we could re-use a lot of common knowledge for minification. The most obvious one being stripping all possible whitespace characters. On top of that we leveraged more and more domain specific strategies by examining the spec closely. Although the result is not pretty visually we learned a lot of neat tricks in the process that can be very useful in real world applications 🚀🙌

The Double Encoded VNode

2019-03-30T00:00:00Z

Someone in our Preact Slack channel (join here) was running into an issue where the page would be blank as soon as the page loaded. Luckily we got a nice exception logged in the browser console. Error stack traces are awesome as they point you directly to the portion where the error occured and allow you to follow back the trail to see how the error came to be.

preact.mjs:256 Uncaught DOMException:

  Failed to execute 'createElement' on 'Document': The tag name provided
  ('[object Object]') is not a valid name.

    at C (webpack-internal:///../node_modules/preact/dist/preact.mjs:213:155)
    at x (webpack-internal:///../node_modules/preact/dist/preact.mjs:175:16)
    at b (webpack-internal:///../node_modules/preact/dist/preact.mjs:108:83)
    at j (webpack-internal:///../node_modules/preact/dist/preact.mjs:262:32)
    at eval (webpack-internal:///./main.debug.tsx:9:54)
    at Module../main.debug.tsx (http://localhost:8080/app.bundle.js:1126:1)
    at __webpack_require__ (http://localhost:8080/app.bundle.js:724:30)
    at fn (http://localhost:8080/app.bundle.js:101:20)
    at Object.0 (http://localhost:8080/app.bundle.js:1139:18)
    at __webpack_require__ (http://localhost:8080/app.bundle.js:724:30)

Unfortunately the code is minified and the sourcemaps didn't seem to work which explains the single letter function names. Nonetheless the error message gives us a few clues. It looks like there is a function called createElement somwhere that complained about receiving an invalid argument.

Knowing a thing or two about virtual dom libraries (hint I work on Preact) this is very likely about the JSX constructor function. It's the one responsible for turning JSX into virtual-dom nodes (short: vnode) that represent a sort-of template. Most projects transpile it via babel or the TypeScript compiler to plain function calls that js engines can understand.

<div /> -> createElement('div');

// with props
<div class="foo" /> -> createElement('div', { class: 'foo' });

// with children
<div>foo</div> -> createElement('div', null, 'foo');

These in turn convert the arguments to a vnode:

const vnode = createElement("div", { class: "foo" });
console.log(vnode);
// Logs:
// {
//   type: 'span',
//   props: { class: 'foo' }
//   text: null,
// }

Note: Nearly all virtual-dom based frameworks work with a similar shaped object under the hood. Some rename properties like nodeName instead of type but that's mostly it.

So it's this function is called with something it doesn't like. Let's look at the code that triggers it:

// foo.js
export default <div />;

// app.js
import { render } from "preact";
import Foo from "./foo";

render(<Foo />, document.getElementById('root));

Nothing out of the ordinary and it looks like a typical setup for any modern web app. The browser's debugger was pointing at the highlighted line where the render function is called. It seems innocent, but something must be up with it. Since the render function strangely didn't turn up as part of the stacktrace we'll have trouble finding the right place to set a breakpoint. Following imports is usually not much fun when you can't cmd/ctrl+click a variable like you can in vscode or similar IDEs.

In these situations there is one neat little trick we can do without having to dive into the code of the library in use (that's Preact in this example).

import { render } from "preact";
import Foo from "./foo";

// Wrap it and log first argument
function render2(arg1, dom) {
  console.log(arg1);
  render(arg1, dom);
}

// call our wrapped function
render2(<Foo />, document.getElementById('root));

And sure enough we receive something suspicious:

{
	"type": {
		"type": "span",
		"props": {},
		"text": null
	},
	"props": {},
	"text": null
}

Well that's odd, it seems like the type-property isn't just the string span but holds another object that looks like another vnode. This nesting is probably invalid, so let's look again at our code and search for any hints. To make this easier for myself I disabled sourcemaps in the browser's devtools.

// foo.js
import { createElement } from "preact";
export default createElement("div", null);

// app.js
import { render } from "preact";
import Foo from "./foo";

render(createElement(Foo, null), document.getElementById("root"));

Wait a second, two calls to createElement? Do we double encode our JSX element? Yup, we do! We already apply our JSX constructor in foo.js, so we don't need to pass it through createElement again. The fix is easy:.

// replace this...
render(<App />, document.getElementById('root'));

// ...with this
render(App, document.getElementById('root));

So what did we just do there? How did we go from an error to finding the cause?

1. Identification 💥

The most important part of any debugging story is finding a way to get to an error or into an incorrect state. Only after one has identified the error is one able to fix it. In our case it was quite easy as just firing up the browser lead to a nice stack trace and we didn't have to go through any additional steps to reproduce it. We're not always that lucky.

2. Isolation🔧

Once the issue has been identified we need a way to reduce the amount of code we neeed to step through. The less code that causes the error, the better. If you have a stack trace you can often walk it backwards and ignore the rest of your code. For frontend applications you can usually narrow it down to a few or even a single component.

3. The Fix ✅

At this point you should have found the error and are able to reproduce it in isolation. Now comes the hard part of finding a fix for it. This is highly specific to the code you're working on so it's hard to make some general rules here. What I find most useful is trying to understand the state or context of the currently executing function.

When there is an issue in Preact we need to be very aware of the shape the current vnode tree is in. Knowing that is usually half the work to finding a proper fix.

Conclusion

We fixed it! With some ciritical thinking we were quickly able to pin-point the issue to a vnode being encoded twice. That's one more happy Preact user 🎉 Over the years I've taken the 3 steps to debugging by heart and they are still the same principles I apply when working with unfamiliar code bases🍀

When should I use preact compat?

2019-03-23T00:00:00Z

What's the difference between preact and preact/compat? That's a great and one of the more popular questions if you check out the preact tag on StackOverflow. Preact advertises itself as the thinnest possible virtual-dom 3kB abstraction over the real DOM with a react-like API 🚀. This sentence is quite a mouthful, but the key is the last part: "react-like API".

While the high-level concepts are very similar in any virtual-dom based library, we all implemented them differently. The beauty about this is that as a user you likely won't notice it and can reuse your existing knowledge for building modern Single-Page-Applications (=SPA). This typically includes reyling on several third-party libraries that are available on npm and oh boy are there many of them!

So we looked at ways on how we can leverage existing libraries. We didn't want to put the workload on the community by asking them to rewrite everything for Preact and instead decided to provide a compatibility layer that sits above Preact. That's why it's called preact/compat. So what does the compatibility layer contain that makes libraries written for React seamlessly work with Preact?

The curious case of the Children API

If you ever wrote components that resemble a generic list like an AutoSuggest-component you'll likely want to wrap each list item with something for styling or other purposes. To do this you need a way to iterate over the children and wrap each child with an <li>-tag for example. The thing to watch out for is that props.children is not guaranteed to be an array, so you can't just call props.children.map(fn). When is that the case?

// `props.children` will be an object
<Foo>
  <Bar />
</Foo>

// `props.children` will be an array
<Foo>
  <Bar />
  <Bar />
</Foo>

To solve this React provides a wrapper that can map over props.children in a similar way like you would for an array.

import { Children } from "react";

function AutoSuggest(props) {
	return (
		<ul>
			{Children.map(props.children, child => {
				return (
					<li key={someId} className="fancy-list">
						{child}
					</li>
				);
			})}
		</ul>
	);
}

Besides the map() function the Children-API supports a few more methods:

API	Description
`Children.forEach(children, fn)`	Apply `fn` on each child, returns `void`
`Children.map(children, fn)`	Apply `fn` on each child and return an array of children
`Children.count(children)`	Returns the number of children
`Children.toArray(children)`	Converts children to an array
`Children.only(children)`	Throws when there is more or less than 1 child

If you squint slightly all these methods are very similar to those found on a standard array. They even share the same name in fact. Historically children have always been an array in Preact. This means that you could always savely call props.children.map etc. For Preact X we unfortunately had to change this to support parsing ambiguities with Fragements. Nonetheless we've kept the ease of use of arrays and provide our own method to convert props.children to an array:

import { toChildArray } from "preact";

function AutoSuggest(props) {
	return (
		<ul>
			{toChildArray(props.children).map(child => {
				return (
					<li key={someId} className="fancy-list">
						{child}
					</li>
				);
			})}
		</ul>
	);
}

The advantage of this is that our API surface remains small. You don't have to learn any new ways to count the items in an array because already do know that. So effectively the Children-API can be replaced with straight array methods in Preact:

API	Array Method
`Children.forEach(children, fn)`	`arr.forEach(fn)`
`Children.map(children, fn)`	`arr.map(fn)`
`Children.count(children)`	`arr.length`
`Children.toArray(children)`	`toChildArray(children)`
`Children.only(children)`	needs to be implemented manually

An argument can be made that creating an array when there is only a single child present is wasteful, but we happily trade that of for a much simpler API. That single allocation is so tiny, that it's extremly difficult to measure even with microbenchmarks.

Unmounting a root node with style

Although it's quite rare, there are some instances where you need to destroy a root node. A root node referes to the topmost node of a tree. It's the one you passed into render() with your component as the first argument.

Adding another function export in our code base is always expensive for size reasons and we always try to avoid adding any new exports. Instead we can leverage the fact that null is alwayst treated as an empty value throughout our whole code base. Because of that we can literally just call render() with null to destroy a root node:

import { render } from "preact";

const App = () => <h1>Hello World</h1>;
render(<App />, document.getElementById("root"));

// Destroy the root
render(null, document.getElementById("root"));

Even our compatibility layer in preact/compat for unmountComponentAtNode does just that:

import { render } from "preact";

// Remove a component tree from the DOM,
// including state and event handlers.
function unmountComponentAtNode(container) {
	if (container._prevVNode != null) {
		render(null, container);
		return true;
	}
	return false;
}

PureComponent and memo()

Both the PureComponent class and the recently introduced memo() function are ways to specificy a comparison function to potentially skip out of an update. PureComponent is for classes and ships with a default implementation for shouldComponentUpdate. memo() is for functional components respectively and does the same thing. They are both meant to improve performance when the wrapped components are so expensive to render that they effect the user experience negatively.

In our experience this is only true for a very tiny percentage of apps built with Preact. Nearly all performance issues are caused by code that unnecessarily calls setState or forceUpdate. Of course you can always try to solve it with memo or PureComponent but solving the issue at the root is much more beneficial and in my experience easier to reason about. It usually also makes the code easier to read, which is always a plus!

What about forwardRef?

forwardRef is an interesting one, because it's a solution to a problem that we framework authors hope to avoid in the first place. The problem is that the ref and key properties are filtered out of the props object:

function Foo(props) {
	console.log(props.key, props.ref); // logs: `undefined`, `undefined`
	return null;
}

render(<Foo ref={whatever} key="bob" />, dom);

Even though we passed both properties explicitely to Foo, they won't be available anymore on props. This is caused by createElement filtering out those two properties. forwardRef was brought into existance to pass ref back into a component, because it turns out that forwarding ref properties is very useful for libraries.

import { forwardRef } from "preact/compat";

// Some high-order component
function withLog(Wrapped) {
  return forwardRef((props, ref) => {
    return (
      <Foo>
        <Bar>
          <Wrapped {...props} ref={ref} />
        </Bar>
      </Foo>
    );
  };
}

What if we just didn't delete ref from props? That would make forwardRef completely unnecessary and there even is an open RFC for that over at the react repo. We had this at one point in Preact X before going alpha and filtered it out to stay compatible with React. Naturally we're very excited about making the API surface slimmer and reusing existing solutions ✅.

Personally I think we should go back and only remove ref from props in preact/compat. This should be an easy change to make and would be a good first PR 🎉 With that change in place could simply be rewritten to be a standard functional component, no forwardRef is needed:

// Some high-order component
function withLog(Wrapped) {
  return props => (
    <Foo>
      <Bar>
        <Wrapped {...props} ref={props.ref} />
      </Bar>
    </Foo>
  )};
}

Patching in React-specific properties

In my last blog post we talked about using Preact's option hooks to modify our data structures. We use it to add properties that we don't use but many third-party libraries check for. These include $$typeof to check if an virtual dom node was created by createElement, Component.isReactComponent which is just a simple boolean flag and a few more. These just have to be there but aren't really used in Preact.

Conclusion

Phew I wrote more than I intended to but I hope that this quick overview gives you an idea why preact/compat exists and why certain things are not found in the core library. If you feel like something is missing, feel free to get in touch or file an issue on our repo in github 👍

Preact's best kept secret

2019-03-17T00:00:00Z

I though I'd start the blog with something special that not many Preact users may know about. It's one of the least known features and also one of the most powerful ways to extend Preact: Option-Hooks. They allow anyone to plug into our reconciler and extend Preact without needing to make any modifications in our core. This power is what enables us to ship various addons like preact/compat and preact/hooks to name a few. They've been in Preact since the very early days reaching back to 2015 ✅.

⚠ Note: Internally they've always been referred to as hooks in our code base. They are not to be confused with the recent hooks feature that was introduced by the react team.

At the time of this writing we expose 9 hooks for the various reconciliation stages:

options.vnode: Allows to mutate a vnode just before passing it to the reconciler
options.commit: Called when a whole vnode-tree is mounted or updated
options.unmount: Called when a vnode will be removed from the DOM.
options.diff: Called right before a vnode is compared against the previous one
options.render: Called right before rendering a component
options.diffed: Called after the comparison between 2 vnodes finished
options.event: Called when an event handler will be dispatched
options.requestAnimationFrame: Called when a layout effect will be scheduled
options.debounceRendering: Called when an update is scheduled

Note: vnode (= virtual DOM node) is the data structure at the heart of Preact and is used thorough the diff process to compare elements to each other.

You may rightfully ask why we didn't choose more descriptive name for these. The reason behind is our strong focus on bundle size. By re-using words that can already be found elsewhere in our code we can play in the hands of the gzip compression algorithm ✌️. It's optimized to optimally compress repeating patterns and we have quite a few of them.

Extending Preact via addons

A great example of where they're used is in the recently added preact/hooks addon. Whenever a hook is invoked it will be attached to the current component so that it can be called again once the component rerenders. But because hook functions don't receive any reference to the component through any function arguments, we need to keep track of the current component through other means. For this we can leverage options.render to just store the reference in a variable and options.diffed after it's done rendering to flush any pending effects.

import { options } from "preact";

// Reference to the component that's currently rendering
let currentComponent;
// Index into array of hooks on a component instance
let currentIndex;

// Keep track of the current component and index of the hook. Each hook will
// increment the index automatically.
options.render = vnode => {
	currentComponent = vnode._component;
	currentIndex = 0;
};

// Schedule any pending effects after the component is done rendering
options.diffed = vnode => {
	const hooks = vnode._component._hooks;
	hooks._pendingEffects.forEach(effect => invokeEffect(effect));
};

preact/compat employs a similar trick: To make third-party libraries belief that we are React we need to patch our internal vnode structure with React-specific properties. Many 3rd-party libraries explicitely check for them and will bail out if they are missing. So we need to apply normalizations as early as possible before any 3rd-party code is run. In our case we chose to do this right when a vnode is created in createElement (or h). Internally it relies on options.vnode to do the magic:

// Pseudo implementation for jsx constructor
function createElement(type, props, ...children) {
	const vnode = createVNode(type, props, children);
	if (options.vnode) options.vnode(vnode);
	return vnode;
}

// In `preact/compat`:
options.vnode = vnode => {
	// Add react-specifc $$typeof property
	vnode.$$typeof = REACT_ELEMENT_TYPE;
};

Besides allowing addons for greater ecosystem compatibiliy the options hooks open up a whole world of experiments and prototypes. We have a plethora of them spread out over gists, codesandboxes and fiddles that prototype various ideas. These quick prototypes are a lot easier to share and allow us to evaluate if it's any good before spending the time integrating it natively into core.

One of our users Rasmus Schultz for example shared a different form of components an alternative to hooks.

Hooks re-imagined

They're largerly inspired by the way components are handled in ivi which leverages closures to circumvent the need to keep track of the current component. Previously we established that we only need to do that because a hook doesn't receive the component reference in any function argument. This way of declaring components does exactly that:

const Counter = component(instance => {
	let value = 0;

	function count() {
		value += 1;
		// `invalidate` is conceptually the same as `setState`
		invalidate(instance);
	}

	useEffect(instance, () => console.log(`You clicked ${value} times`));

	// Return a function (=render method)
	return props => (
		<button onClick={count}>
			{props.title}: {value}
		</button>
	);
});

Just by wrapping our component implementation with a function that initializes it. Instead of returning the virtual DOM directly, it returns another function as the render method. The outer function is used to initialize all hooks or event handlers and basically acts as a constructor for the render method. This has the benefit of not having to re-create functions on each render.

The downside is that props can only be accessed via a reference to the instance. They are not value bound anymore which can lead to tearing when mixed with asynchronicity. Nonetheless this is a great alternative to hooks which just chooses a different set of tradeoffs. And we always love and encourage such experiments. Before you know it these may turn out to be something really cool ⚡.

Remember even Preact X just started out as a random experiment and before we knew it, turned into the next major version for Preact. For that reason our option hooks our little secret allowing us to quickly iterate and prototype new ideas 🙌.

Marvin Hagemeister

Signals vs Query-Based Compilers

Old Days: The Pipeline Architecture

Modern: Query Based Compilers

Queries, Inputs and the Database

Caches, caches and more caches

Shape of a Query

Inputs: The source of truth

To change or not to change

The secret sauce: Revisions

What about threading?

Which one is better?

Building From First Principles

Online !== Offline

Intentionally choosing boring tech

Clarity is key

The missing link in JavaScript tools

The template predicament

A Virtual File System as the Unifying Layer

Cross-Language usage

Conclusion

Speeding up the JavaScript ecosystem - Semver

Parse, don't validate

Does slapping a cache in front of things help?

How fast can we make it?

Conclusion

Speeding up the JavaScript ecosystem - Rust and JavaScript Plugins

The Rust plugin dilemma

Serialization and deserialization costs

Flattening the AST

Lazy deserialization

Bonus: Supporting all the languages

Conclusion

The modern way to write JavaScript servers

Request, Response and Fetch

How do I launch my server?

Conclusion

Speeding up the JavaScript ecosystem - Isolated Declarations

Packaging for npm in 2024 is a mess

Why generating .d.ts files takes so much time

Entering a new era of packaging

Using it in production

Conclusion

Speeding up the JavaScript ecosystem - Server Side JSX

Optimizing JSX for the server

Mixing static and dynamic parts

Making it secure

What about components?

How much faster is it in the real world?

Conclusion

Speeding up the JavaScript ecosystem - Tailwind CSS

Switching things up

How Tailwind CSS works

Optimizing the extraction stage

Regexing all the things

Turning class names into CSS

What about Rust?

Conclusion

Speeding up the JavaScript ecosystem - The barrel file debacle

Gathering more information

Anatomy of a barrel file

Everything is not fine

Effects of barrel files on performance

What to do

Speeding up the JavaScript ecosystem - Polyfills gone rogue

Polyfills that don’t polyfill

Doing a little bit of housekeeping

Filling up everyone's disk space

So you want to render colors in your terminal

Humble beginnings

Supporting all the colors

Detecting color support

Color conversions

Can we do better?

Conclusion

Speeding up the JavaScript ecosystem - draft-js emoji plugin

Finding a solution

Conclusion

Speeding up the JavaScript ecosystem - npm scripts

Loading only the code you need

Why generating `.d.ts` files takes so much time