Git is the version control system. Yes, others exist, but if you're writing code you're probably using git.

Git was not designed with people's names changing in mind. This is a problem, because people's names do change for many reasons. The most common one many people will be familiar with is women changing their surname when marrying a man.

The one I am concerned about is the name change that trans people go through as part of a social transition. Unlike changing a surname at marriage, in which a person's "maiden name" can remain common knowledge, changing your name during a transition leaves behind what we commonly call a "deadname".

Revealing a trans person's deadname is a safety issue, which is a problem when working with git.

Removing your deadname from displayed logs

There is a built-in utility in git that allows displaying commits with an updated name. That is git mailmap. It allows you to create a `.mailmap` file in the root of a git repository that contains lines like this:

Correct Name <correct.email@company.tld> <commit.email@company.tld>

With a .mailmap file in place, git tools such as git log and git blame will display names found in a .mailmap file for commits that used an email address identified in there.

In order to find out what email addresses might exist against your deadname, you can run this command to see what commit authors exist in a repo's history:

git shortlog --summary --email

This will display an alphabetical list of commit author names and their associated email addresses, with the number of commits listed to the left. The same name with a different email address is treated as a different commit author.

Adding a .mailmap file is a useful way to effectively update the name against all your old commits without having to rewrite git history. This is useful because rewriting history is often not an option, especially in work environments.

However, this approach has some downsides as well:

• If the email address used for your commits contains your deadname, as is common in work environments, then it will be exposed to anyone viewing the .mailmap file.
• GitHub, by far the most commonly used git hosting platform, at the time of writing does not support .mailmap and will still display your deadname against your old commits.
• The original log, including your deadname, still exists and can be revealed by modifying or removing the .mailmap file.

These shortcomings are only surmountable by rewriting history.

Removing your deadname from commit author data

Git does have a built-in feature called filter-branch that can be used for rewriting history, but for years now it's been recommended against. Instead, the git documentation now officially recommends the use of an external Python script called git-filter-repo.

You can use git-filter-repo to rewrite the history of a git repository. It expects to always be run against a fresh clone of your repo, so before using it you should create a fresh clone to work in. Using git-filter-repo will also remove your repo's remotes, this is intentionally added friction to encourage verifying your changes before force pushing them to the remote.

You can use git-filter-repo to modify author information against commits based on the contents of a .mailmap file:

git filter-repo --use-mailmap

If you want to use an external file (e.g. because a .mailmap file already exists for this repo and you only want to rewrite _your_ commits) you can also use an external file like this:

git filter-repo --mailmap <filename>

Note that, because git-filter-repo expects to work on a fresh clone, you'll want your external file to exist outside your repo's root directory.

Once you've done this, you can re-check the list of commit authors using git shortlog like in the example above. Make sure to remove any of your lines in a .mailmap file first, so you don't accidentally obscure any commits under your deadname at this point.

Once confirmed, you can add your remote back and force push your changes, e.g.

git remote add origin <url-to-origin>
		git push --all --force

Removing your deadname from committed files

Rewriting history like this won't remove a .mailmap file. If you don't want that file in your repo's git history either because it reveals your deadname then you'll need to remove it. If you want it removed from the history itself, you can also use the sensitive data removal feature git-filter-repo to rewrite history in a way that removes a file completely.

Remember, you'll need a (new) fresh clone to do this.

git filter-repo --sensitive-data-removal --invert-paths --path .mailmap

If you have other files that may have once contained your deadname, such as a package.json file, you can also use the sensitive data removal tool to change these.

First, you'll need to create an expressions file defining what text to replace. For example:

Deadname==>My Name

Then you can run a history-rewriting find and replace using that file by running this command:

git filter-repo --sensitive-data-removal --replace-text <path-to-expressions-file>

Be very careful with this step, as a global find and replace could result in unanticipated changes.

Once you're finished removing this sensitive data and you've verified that it worked as expected, you can force push your changes to update the history on the remote.

git push --all --force

Feedback

If you know of any other tips for removing your deadname from a git repo, I'd like to hear them! Please email me your feedback.

TypeScript is a really useful tool for finding potential issues with JavaScript code while it's still in your IDE. It works by letting you annotate your JavaScript with type information, so your IDE has enough information to tell you if you're treating something like it's a different type.

The main downsides of using it are that you need a build system with a step that strips out all the type annotations to leave you with plain JavaScript that browsers can understand, and that it's a new language to learn on top of JavaScript. Personally I think the upsides well outweigh the downsides, and I use TypeScript in all my JavaScript projects now.

In this article, I want to go over a pattern that I've found particularly useful, which relies on a few TypeScript features.

I really like using discriminated unions, where I might have code that needs to handle several different types of object. That code might look something like this (swap out if/else if for switch/case if that's what you prefer):

if (item.type === ItemType.TYPE_A) {
	// Do something to handle type A
} else if (item.type === ItemType.TYPE_B) {
	// Do something to handle type B
}

The danger of this approach, in regular JavaScript, is that if you ever add a new type to your list of types, it needs to be handled somehow in every place where you have a block like this. That's where TypeScript can come in, by taking advantage of function overloads:

export function assertAllUnionMembersHandled(value: never): never;
export function assertAllUnionMembersHandled(value: unknown): never {
	throw new TypeError(`Union member ${value} was not handled.`);
}

When defining function overloads with TypeScript, first you list each function signature (starting with the most specific, as the first ones take priority) and then you write the actual function implementation with its own signature. When you call the function, the implementation signature is essentially ignored, so in this case your IDE will treat it as having the signature (value: never) => never.

This means, if you try to pass in anything that TypeScript thinks has a type other than never, your IDE will highlight it as an error. never is a funny type, I find it's most useful to think of it as a union type with zero members. So as you narrow a member type like 'A' | 'B' | 'C', once all three members have been removed through type narrowing you'll have zero members remaining, and that's never.

You can take advantage of this when handling all members of a union type by calling this function in the else (or default) part of your block:

if (item.type === ItemType.TYPE_A) {
	// Do something to handle type A
} else if (item.type === ItemType.TYPE_B) {
	// Do something to handle type B
} else {
	assertAllUnionMembersHandled(item);
}

Now, if you extend item to have a third possible type, TypeScript will see item.type as having that new member as its type, and highlight it as an error. If you have followed this pattern in every place where you need to handle each different member of a union type, they'll all be identified as errors that can guide you to handling your new type wherever necessary.

Here's an example in the TypeScript Playground where using this function highlights an error where a union member is unhandled. Unfortunately, you'll see that the error message is not exactly clear:

Argument of type '{ type: "C"; value: boolean; }' is not assignable to parameter of type 'never'.
The call would have succeeded against this implementation, but implementation signatures of overloads are not externally visible.

const item: {
	type: typeof ItemType.TYPE_C;
	value: boolean;
}

That's the biggest downside of this function. It highlights where those errors are, but not in a way that's particularly useful if you don't already understand how it's used or what those errors mean. The best way I've found so far for managing this is to add an explanatory JSDoc comment to the assertAllUnionMembersHandled function itself, so if anyone is confused by the error and hovers over the function itself, they can see an explanation of how to resolve errors like this. For example, this is the relevant part of the JSDoc comment I use in the code for Orange Twist:

Investigating an error?

You probably need to add additional code to handle one or more values of an enum or another union type.

You can hover over the argument passed into this function to see the values that aren't handled currently. For example, if you see:

const foo: "A" | "B";

That means the union members 'A' and 'B' were not handled.

If the code is run without fixing any type errors, the default behaviour in my example above is for it to throw an error. That can show up in the browser console during runtime, but it's a lot easier to take advantage of static analysis to find and fix these errors before they ever reach the browser than it is to make sure you're testing every possible code branch so you won't miss a potential thrown error.

Orange Twist has been my main personal project just over a year now. It's a web app for managing tasks and notes, which I've tailored to work the way I think. But it's also my playground where I toy with new web technologies, experiment with different approaches, and find myself running into new obstacles that force me to learn.

If you like coding, I can't recommend having a personal project highly enough. I've found it to be a wonderful learning tool. It's been especially gratifying to also build something useful. I've been using Orange Twist to manage its own development, my work tasks, and my general life admin tasks.

This article is about some new stuff I learned and used while working on Orange Twist recently, where I managed to improve the performance of its first load.

Orange Twist's initial load

Orange Twist is built with Preact, and it stores all its data in the browser. Since it's hosted on GitHub Pages, my only option for a back end is a static HTTP server anyway, and I like the way keeping all a user's data on their machine and never sending it to a server goes against the grain of some of the modern web's worst tendencies.

Recently, in my day job where I work on the front end of a different web app, I've been trying to figure out how to improve UI performance. It's turned out to be more interesting and less frustrating than I'd expected, so I've also ended up looking into improving the performance of Orange Twist too.

There are a few different potential sources of slow performance of websites and web apps. Usually an area of focus would be seeing if the back end could respond to network requests faster, but for this app that isn't really a thing (though I was able to find a way to reduce my bundle sizes).

I was definitely noticing a lag in the app loading initially, especially when using it on my phone. It would sort of stutter rapidly through a few different iterations of partially loaded data, before finally finishing.

When Orange Twist's main page first loads, there are essentially two things it needs to do:

• Load a few different pieces of data out of an Indexed DB
• Use Preact to render the DOM tree based on that data, once it's loaded

I've been using Orange Twist for quite a few months now, which means I've accumulated some data. On the main page, Orange Twist renders out a section for each day that has data, and those days might render a note and a set of tasks with names and statuses.

When the rendering is finally done, then it scrolls to the section for current day, which is useful but unfortunately felt like another bit of jank during the initial load.

This animation doesn't have the real timing, but it shows the steps that the browser would stutter through on each load:

The event loop

A brief aside before we get into what I found and what I changed, it's useful to have some understanding of the JavaScript event loop. I highly recommend Lydia Hallie's excellent video on the topic (seriously I wish I had this resource when I was a junior developer):

JavaScript Visualized - Event Loop, Web APIs, (Micro)task Queue

But to state the relevant bits briefly, a JavaScript task runs on the main thread, also known as the UI thread, and while a task is running the browser can't paint any updates to the page.

Many web APIs, like setTimeout, queue up a new task to run at a later time. These allow the browser to take a break in between tasks to do other work, like painting the page.

Newer Promise-based APIs will queue microtasks instead, and a task won't finish until all queued microtasks have also completed. Often these will result in new tasks anyway, but some code (like using Promise.resolve to create a Promise that's already resolved) can extend the duration of the current task.

So if the browser tab looks "frozen", it's probably because there's a long-running task that's occupying the main thread. Now, back to the performance stuff.

Janky loading

I've found the performance profiling tool in Chrome's developer tools particularly useful for getting a rough idea of why the browser is behaving in a particular way during this initial load. While it can let you drill right down into individual functions getting called if you need that level of detail, at the top level it will do useful things like highlight long-running tasks.

For example, here's what running the profiler during the initial load of a production build of v1.5.3 of Orange Twist (before any performance fixes) looks like on my machine:

The first thing I found was causing a slowdown was that Preact was having to re-evaluate the DOM tree after each piece of data was loaded from Indexed DB. By making it wait until all the data was loaded before it rendered anything using that data, I was able to reduce the two long tasks into a single long task. This made the initial load look a bit less janky, but it didn't help too much with the overall speed itself.

Deferring some of the work

When Orange Twist has a lot of data, the main page renders quite a large DOM tree. Since I'd already reduced the number of times this tree was being rendered, I started thinking about if there was a way I could make the DOM tree smaller.

Aside from the current day, all of those days Orange Twist renders on its main page are in sections that are collapsed by default. So really, all I need to render initially for each of those parts is their titles. However, there's a really nice feature of the <details> "disclosure" element in some browsers where you can find content in collapsed disclosures using the "Find in page" feature. So I didn't want to just wait until a section was expanded before rendering it because it would break that feature.

My initial thought was to use setTimeout with a randomised timeout, so the sections would be rendered gradually instead of all at once. That should give the browser time to "breathe" so it could render frames and react to user input in the meantime. But then by chance I ran across a web API that I hadn't seen before which seemed perfect for this use case: requestIdleCallback.

The window.requestIdleCallback() method queues a function to be called during a browser's idle periods. This enables developers to perform background and low priority work on the main event loop, without impacting latency-critical events such as animation and input response.

Window: requestIdleCallback() method | MDN

Perfect! Instead of trying to guess when the browser wouldn't be busy by using a random timeout, I could just ask it to wait until it's idle. Unfortunately, Safari doesn't support requestIdleCallback at the moment (though it is supported in the current Technical Preview) so I've still used that random timeout method as a graceful degradation.

After those two optimisations, and a couple of other adjustments to reduce the size of my JavaScript bundle, the time taken for Orange Twist's initial load with my testing data to complete went from 400-450ms down to 90-150ms.

(Those red flags on the yellow boxes are warnings about idle callbacks being delayed, usually by something like 2-3ms)

Unsurprisingly, the initial load of the app feels far faster now. Technically it still takes around 400ms for everything to finish rendering, but because the important stuff is done first and the rest is told to fill in the space when the browser is idle, the app feels (and is!) much more immediately responsive.

There is still a brief flash of the UI without any content loaded, which I'm interested in trying to improve later on. You can see that in this animation, though the timing is tweaked to make it a bit more obvious:

If you're interested in looking at the code changes I talked about in this article, here are links to my PRs against Orange Twist:

• Wait for all data to be loaded before rendering
• Defer rendering hidden content until the browser is idling