Why

This is a performance¹ thing. In the project where I was exploring this, we had a large amount of objects representing configuration values. The possible configuration keys were the same, but different objects had different keys set. This approach was causing some issues:

• Serialization and deserialization produced very large strings because of all the repeated keys.
• Comparison/equality of objects was costly because of the number of keys.
• We needed to do a lot of operations like “find the subset of keys and values that are identical between all of these objects”. This was slow.
• We often needed to update subsets of the items by adding, updating, or removing keys, so each object needed to be an independent clone.

Originally, I planned on doing some sort of object interning to reduce the number of objects we needed to keep in memory at any one time. We would keep only one copy of each unique configuration item, and just reference it in multiple locations. The (now dead) Records and Tuples proposal would have been really useful here, and its replacement, Composites looks like it might help but I didn’t want to tie myself to an incomplete early-stage proposal. So if I went down this route, I’d be building something myself.

While looking all this up, I found Justin Fagnani’s article Composite Map Keys in JavaScript with Bitsets, which is mostly unrelated to what I’m doing here, but did make me think of using bigints in the first place.

How

The basic idea is:

1. Define a bunch of fields, how they should be interpreted, their size, etc. E.g. {name: "size", kind: "uint", bits: 8} to represent a number stored as a u8. You also need to know the offset of each field, this can be calculated from the index of each field and the number of bits in the preceding fields.
2. Add functions getBits(bigint, offset, bits) which does bitshifting to fetch the relevant bits from the bigint backing store, and setBits(bigint, offset, bits, value) which does the opposite
3. For each field, add getters and setters that do the type conversions from e.g. JS number to u8.

Honestly, I was impressed by how well Claude Sonnet handled this stuff. It didn’t produce the tidiest code, nor did it find the clearest ways of doing many things, but the basic bit-bashing was largely correct, and I wrote a lot of tests to confirm that it was working in the way I wanted.

In this use-case, not all keys are present at all times. To handle this, I added an extra store present alongside the bigint backing store that was a simple bitfield where if bit i was 1 in the present store, then the ith field had been set in the main backing store. Deleting a field meant simply clearing the ith bit.

Benefits

• The memory usage of the object is about as compact as it’s possible to be. Booleans take up a single bit, colours can be stored as u32 values (for rgba), fields that were previously string enums are now just a couple of bits wide, etc.
• Deserialization is very quick (basically just BigInt("0x" + value) to convert a hexadecimal string back into our backing store). Serialization is slightly slower because I wanted to ensure that unset fields were zeroed-out first, to ensure consistent representations. The resulting string is pretty compact.
• Lots of operations can take advantage of the present bits to optimise what they’re doing. For example, when checking equality, we can first check that the two present bits are equal to make sure that the same fields are set in both cases. When finding the intersection of two values, we can first AND the present bits together, and check only the fields that are set in both values.

This whole thing is surprisingly usable.

Drawbacks

• Fields need to have a max width. For example, you can’t store an arbitrary string in the bigint, because you don’t know when it will end. If you need dynamically-sized data, then this isn’t going to work.
• Bit operations on bigints is slow. I mean, all things are relative, but in general, gets and sets will be faster with plain old JS objects. HOWEVER: if you have a lot of smaller fields, you can cheat a bit and use a number backing store, or use a combination of a number store for smaller fields and a bigint store for larger fields. Bit operations on number objects are very fast, and in my tests, gets and sets were roughly the same speed as getting/setting regular JS object fields.
• The code is going to be way more complex. Expect to write a whole bunch of tests that basic things like getting and setting a property work. I suspect a good library or layer of abstraction could help here, but, having only done this the once, I don’t know what that abstraction would look like yet.

This might not sound like a lot of drawbacks, but they’re all very significant compared to the more niche benefits of this approach. I wouldn’t recommend doing this in most cases.

Is It Worth It?

I’m not entirely sure yet. This is a bit of an experimental side project at the moment, just playing around with one way of optimising one component of the main project I’m working on. I need to see how it feels to use this approach in practice. The goal is not necessarily that bigints by themselves will make things better, but that they’ll enable other optimisations by having much quicker equality checking, etc, so I need to try out those other optimisations and see the results. If you’re reading this in a few months and still curious, reach out to me on Bluesky or something and ask me how it’s going, and then I can update this blog post with the results.

Consider a complicated expression with multiple sub-expressions. This expression is going to be difficult for the next person reading this code to decipher; we should make it easier for them.

There are a couple of ways to solve this. We could break down the expression into sub-expressions, and assign those sub-expressions to intermediate variables. Or we could pull the expression out into its own dedicated function. In each case, the goal is to give either part or all of the expression a dedicated name. This name helps the next reader to understand the purpose or meaning of the expression.

Unfortunately, names are hard. A good, meaningful name puts the next reader in exactly the right frame of mind to understand what is going on. A bad name can confuse the next reader and make the code less legible than before. And finding the right name is a difficult task. It can’t be too long and unwieldy — being too verbose makes it hard to communicate effectively, as anyone who’s worked with German bureaucracy can tell you. On the other hand, it can’t be too short or generic — naming everything x or var will rarely help future readers.

Sometimes, though, I can’t find a good, obvious name. In these cases, rather than trying to force one, I instead write a comment. A comment gives you more space to work with, which means it can be much more exact and precise than a single name. You can use a comment to remove potential ambiguities that a more generic name might have. A comment also allows you the chance to provide more “why”-type explanation rather than just describing the “what”.

A good name is normally far better than a comment, but good names are hard to come by. If you’re struggling to find the right name for a particular chunk of code, consider whether the context would be better explained as a comment.¹

If you’re in that boat, then here is the answer in tabular form:

In this post, I’ll unpack this table and explain what it means in a bit more detail.

What are side effects?

Side effects in this context is code that:

• interacts with the page (i.e. isn’t deriving new values from existing inputs)
• isn’t handled by the framework itself (e.g. adding onClick handlers to a button via JSX, or using async/suspense).

So for the purposes of this blog post, something like this might be a side effect:

// attach a global event listener from
// inside a particular component
document.addEventHandler("keydown", () => { /* ... */ });

But these probably aren’t side effects:

// derive the `fullName()` signal by
// combining a `firstName()` and `lastName()`
const fullName = () => firstName() + " " + lastName();

// attach an event listener to a particular
// element using JSX
<input onKeyDown={() => { /* ... */ }} />

// this does have side effects, but for the purposes of
// this post, those side effects are handled by SolidJS
const [resource] = createResource(() => fetch(/* ... */));

Are my side effects reactive?

There are broadly two types of side effect:

• Side effects that run once over a component’s entire lifecycle — i.e. some code that should run once when each instance of the component is first rendered, and then cleaned up when the component is unmounted, but never between. These side effects are not reactive.
• Side effects that run multiple times whenever an input changes — i.e. code that will regularly be rerun during the lifetime of the component².

For example, the global keydown handler from before will probably only need to run once: we set the handler when the component is mounted, and then remove it when we’re ready to clean the component up. However, the classic useInterval hook needs to use reactive side-effects: whenever the input parameters change, we need to clean up the old setInterval handler and create a new one.

When should my side effects run?

SolidJS’s side effects can be triggered at two different times:

• Immediately, as the component is being created
• Later, once the component has been mounted to the DOM and is ready to be used

Some things only make sense once the component has been mounted: any code that needs to access ref, for example, should run after the element has been created and attached to the DOM³.

Some things are not so clear-cut though. For example setInterval doesn’t require any access to the DOM or to any particular elements, so it might make sense to put it in the “run immediately” category. In practice, however, setInterval should normally only run once the component has been mounted. Why?

The answer is server-side rendering. When a component is rendered server-side, the DOM is never mounted per-se, so side effects that run only once mounted are never run. However side effects that run immediately are run, because they will probably affect how the component will be rendered. In fact, that’s normally the point of having them run immediately in the first place, so they can affect rendering!

If we put setInterval in the “run immediately” category, then it will be run on the server. But the render code will never wait for the interval handler to actually start, it’ll just carry on generating HTML and sending it to the client. And once the HTML has been generated, the component will be unmounted, the setInterval handler will be cleared, and the code in it probably won’t have even had the chance to run once, let alone affect how the code gets rendered⁴.

This won’t break anything (as long as the interval is correctly cleared), but it is a useless call to setInterval, and a useless resource that needs to be allocated and cleaned up at some point. Therefore, if you’ve got a side effect and you’re sure it won’t affect rendering, consider running it only once the DOM has been mounted.

Bringing it together as a table

If we combine the two questions above, we end up with four different cases, as shown in the table I showed earlier:

To finish up, let’s look at those four cases individually.

• createEffect: The first run always happens after the component is mounted. After that, if a signal used in the body of the effect changes, the effect will be rerun. If no signals are used in the body, then this behaves the same as onMount.
• onMount: As the name says, this also happens after the component is mounted, but it is not reactive. This is good for side effects that only need to run once that use the DOM.
• createRenderEffect: Reactively, this behaves the same as createEffect, but the first run will happen immediately (i.e. synchronously before the createRenderEffect is completed). Similarly to createEffect, if no signals are used in the body of the effect, then this behaves the same as running the code in the body of the component.
• no function needed: Remember that the body of your component will only get called once during the component’s lifetime, so non-reactive side-effects that need to run immediately (such as instantiating a third-party library, or using createUniqueId) can be called as part of that body.

Addendum: onCleanup

A lot of side effects require some sort of cleanup to happen later — for example, starting a setInterval timer requires cleaning up that timer when it’s no longer needed. For that, SolidJS provides the onCleanup function.

As a rule of thumb, onCleanup can be called wherever there is a scope that would get cleaned up at some point. For example, once a component is no longer being rendered, it needs to be cleaned up and removed from the DOM. By calling onCleanup in the component body, you can add an extra callback that will be called when that happens.

For reactive effects (createRenderEffect/createEffect), calling onCleanup inside the effect callback will schedule a function to run when the effect is re-run, i.e. when a signal triggers the effect to restart, all onCleanup functions will get called, and then the new effect is run.

In general, put your onCleanup calls inside the function you use to create your side effect in the first place. For example:

// NO!  Don't do this!
onMount(() => {
  /* some side effect */
});
onCleanup(() => {
  /* some clean up */
});

// ----

// YES!  Do this!
onMount(() => {
  /* some side effect */
  onCleanup(() => {
    /* some clean up */
  });
});

This is because generally you only want the onCleanup to run if the side effect was called in the first place. As mentioned earlier, functions like onMount and createEffect will not run during SSR, but if the onCleanup isn’t inside one of those functions, then it will still be called during SSR, doing unexpected things.

Addendum: Avoiding effects

At the start, I made the comparison to React’s useEffect, and in a footnote pointed out that in modern React, useEffect is generally discouraged — there’s often a better way.

In SolidJS, createEffect doesn’t behave in quite such surprising ways as useEffect, thanks in large part to the automatic dependency tracking that means that the effect normally re-runs when you’d expect it to re-run. However, it’s still a good idea to look out for cases where you can replace createEffect with a better option. When I look at createEffect calls, these are the things I’m looking out for:

• Is a signal setter being used in the body of the effect? If so, the effect can almost certainly be replaced by createMemo or another form of computed signal.
• Is an async function being called in the effect? If so, it might be worth using createResource (or createAsync from Solid Router) instead, as this will handle some of the boilerplate for you, as well as integrating with the suspense mechanism.
• Is the effect setting an event handler on a DOM element? If so, use the on* handlers in JSX instead. This seems obvious, but I’ve written this sort of code before, only to realise later that I’d missed an obvious and easier solution.
• Is the function body reactive and/or would the effect work better if it was run immediately? As discussed in this article, other functions for running side effects are available.
• Is there a function that already handles this case in a Solid Primitives package, or can you write your own wrapper around the effect to encapsulate it a bit better? This one isn’t really about getting rid of effects, but rather hiding them somewhere else. But encapsulation is good, and the Solid Primitives functions are generally useful, even if you’re just looking at the source code to get a hint of how to do something.

The problem happens with an application that looks something like this:

const app = Fastify();

app.register(ws);
app.register(fastifyCookie);
app.register(fastifySession, { secret: "..." });

app.register(fastifyTRPCPlugin, {
  prefix: "/trpc",
  useWSS: true,
  trpcOptions: {
    router,
    onError,
    createContext: ({ req }) => {
      console.log(req.session); // logs "undefined"
      return {};
    },
  },
});

The useWSS parameter passed to the tRPC plugin means that it can handle both standard HTTP requests and a persistent websocket connection. Theoretically, both of these kinds of requests get handled by Fastify first, and therefore both should be initialised with a session object¹. In practice, though, the session field is missing on all websocket-based connections, but present for all HTTP-based connections.

The cause is that the Fastify adapter for tRPC delegates to the non-Fastify-specific websocket adapter. When that creates a context, the incoming req object is an instance of IncomingMessage, i.e. the underlying NodeJS request abstraction, which does not have the Fastify session details attached.

This probably should be better documented, ideally directly in the types (although that would probably be a fairly large breakage), or at least in the Fastify documentation.

The best solution I found is a WeakMap mapping IncomingMessage requests to FastifyRequest values, which have the expected session attribute. That looks something like this:

// create a new scope so that the hook we add later will only
// affect tRPC-specific requests
app.register((app) => {
  // use a WeakMap to avoid leaking memory by holding on to
  // requests longer than necessary
  const REQS = new WeakMap<
    FastifyRequest | IncomingMessage,
    FastifyRequest
  >();

  app.addHook("onRequest", async (req) => {
    // associate each raw `IncomingMessage` (`req.raw`) with
    // the original `IncomingMessage`
    REQS.set(req.raw, req);
  });

  app.register(fastifyTRPCPlugin, {
    prefix: "/trpc",
    useWSS: true,
    trpcOptions: {
      router,
      onError,
      createContext: ({ req }) => {
        // given either a `FastifyRequest` or an
        // `IncomingMessage`, fetch the related
        // `FastifyRequest` that we saved earlier
        const realReq = REQS.get(req.raw ?? req);
        if (!realReq)
          throw new Error("This should never happen");

        console.log(realReq.session); // logs the session object
        return {};
      },
    },
  });
});

Because the tRPC types aren’t correct for the req parameter of the createContext callback, you might need to fiddle with the Typescript types to get this to work properly. Specifically, the WeakMap type here is technically incorrect, but means that I can do REQS.get(req.raw ?? req) without Typescript complaining. This does cause an ESLint error (because according to the type definitions, req.raw can never be null), but I’d rather silence an ESLint error than a Typescript error.

I hope this helps you, or myself in six months’ time when I run into this issue again having forgotten about it completely.

The Journey to Using using

Many classes or objects represent some sort of resource, such as an open file or a database connection, that requires some cleanup logic when that resource is no longer in use. In NodeJS, the convention is typically to put this cleanup in a close() function. For example, the Server class in node:http has a close() method that stops new connections and closes existing ones.

The problem with close alone is that it’s easy not to call it. Sometimes it’s a matter of forgetting, but often errors and exceptions can trip us up. Consider this function:

async function saveMessageInDatabase(message: string) {
  const conn = new DatabaseConnection();
  const { sender, recipient, content } = parseMessage();
  await conn.insert({ sender, recipient, content });
  await conn.close();
}

This creates a database connection at the start of the function, and closes it at the end. But we have a problem if parseMessage or conn.insert(...) throw an error — in this situation, the saveMessageInDatabase function will stop without closing the connection, leaving unclosed resources hanging around.

The first step to solving this is to formalise how a resource gets closed. We can do this using the Disposable interface or protocol:

interface Disposable {
  [Symbol.dispose]: () => void;
}

This is very similar to methods like .close(), .cancel(), and so on, but we use the well-known symbol Symbol.dispose instead. This helps the runtime to distinguish between objects that have been intentionally made disposable (using this symbol), and objects that happen to have a certain name (e.g. door.close()).

With this in place, we can define the using syntax. using can be used in much the same way as const, and behaves very similarly in most respects.

// was: const varName = new MyDisposableObject();
// now:
using varName = new MyDisposableObject();
varName.method();

However, using has a couple of restrictions in addition to the normal behaviour of const:

• With using, the variable must implement the Disposable protocol — i.e. it must have a Symbol.dispose method that can be called without arguments.
• With using, you cannot destructure the variable you’re interested in (e.g. using { field1, field2 } = disposable()).

When we leave the scope where a using variable was defined (i.e. when we return from the function in which using was used, or leave the if-block, or an exception gets thrown, etc), then the Symbol.dispose method will be called.

In addition, the dispose methods will be called in the reverse order to the way they were defined. So the object that was created first will be disposed of last. This reverse order is deliberate: we don’t want the database to be cleaned up while other resources are still using it!

An example:

function create(data: string) {
	console.log(`creating disposable object with data ${data}`);
	return {
		data: data,
		[Symbol.dispose]() {
			console.log(`disposing disposable object with data ${data}`);
		},
	}
}

function main() {
  using data1 = create("first");
  using data2 = create("second");

  console.log(`using ${data1.data} and ${data2.data}`);
}

console.log("before main");
main();
console.log("after main");

This will produce the following logs:

before main
creating disposable object with data first
creating disposable object with data second
using first and second
disposing disposable object with data second
disposing disposable object with data first
after main

Async Disposables

Often, when we want to dispose of a resource in Javascript, that cleanup/close/disposal operation will need to be asynchonous — for example due to waiting for connections to be cleaned up or data to be flushed.

So in addition to the standard Disposable protocol, there’s a second one, AsyncDisposable. This uses the Symbol.asyncDispose method, which returns a promise that should resolve when the resource is completely closed.

To use an async disposable, we have the await using syntax, which does the same thing as a normal using declaration, but, well, asynchronously. It must be called inside an async function (i.e. it needs to be called in a place where normal await is allowed).

The await using syntax can also handle non-async Disposable objects, which means if you don’t know whether a given resource is going to be asynchronously or synchronously disposed, you can use await using and cover both options.

Collections of Disposables

Sometimes it’s not enough to use function scope to handle resources. We might have a class or object that owns and manages a number of different resources. It would be useful if we could group all of its resources together in a similar way to using, but as a class variable or as part of a closure.

One convenient way of doing this is using the DisposableStack and AsyncDisposableStack classes. These represent stacks of resources managed by the DisposableStack or AsyncDisposableStack object — if we clean up the stack, all the resources that it manages will also get cleaned up. They can be created using the new operator, and provide three different methods for adding resources to the stack:

const stack = new DisposableStack(); // or ` = new AsyncDisposableStack()`

// .use() takes a resource, adds it to the resources managed by the stack,
// and returns the resource so it can be used elsewhere.
// The resource must be a disposable item using the `Symbol.dispose` method
// (or `Symbol.asyncDispose` if using `AsyncDisposableStack`).
const resource1 = stack.use(new MyResource());

// `.defer()` schedules a callback to take place when the stack gets disposed.
const handle = setInterval(() => console.log("running"), 5000);
stack.defer(() => clearInterval(handle));

// .adopt() combines the above two behaviours: it takes a resource and a
// disposal callback, and calls the callback with the resource as its argument
// when the stack gets disposed.  The resource does _not_ need to implement
// the disposable protocol.
const resource2 = stack.adopt(new OtherResource(), (r) => r.close());

Stacks are themselves disposable, so can be disposed of using the Symbol.dispose or Symbol.asyncDispose methods. For convenience, this method is also exposed simple as .dispose() or .asyncDispose(). As mentioned earlier, this method (either using Symbol.dispose/Symbol.asyncDispose or via the alias method) will dispose of all of the resources managed by this stack. Similarly to the using declaration, the resources will be cleaned up in reverse order to prevent issues where resources depend on each other.

Useful Patterns with Explicit Resource Management

Hopefully by now it should be clear what disposable resources are, how they can be manipulated, etc. But it still took me a while to get my head around some typical patterns with disposables, how they can be manipulated, and some best practices. So here are a few short sections which explain a couple of ideas that are now possible, and the best ways to achieve some common goals.

Anonymous Defers

If you’re coming from other languages with features similar to using, such as Go with its defer statement, then you may be surprised that using is really a variable declaration — it’s basically the same as const or let, but it also automatically cleans up resources when the function has completed.

As a result, every time you use using, you need to declare a variable name. But often you don’t want to specify a variable name — e.g. if you want to defer a callback until the end of the function. It’s possible to do something like using _ = ..., using _ as a kind of informal placeholder, but this only works once per function body.

The best solution I’ve found is DisposableStack (or AsyncDisposableStack) and the defer method:

function main() {
	using stack = new DisposableStack();

	console.log("starting function");
	stack.defer(() => console.log("ending function"));

	console.log("during function body");
}

Disposable Timeouts and Intervals

The specification gives a list of various browser and JS APIs that will be retrofitted with the disposable mechanism, but one API that is noticeably missing is the setInterval and setTimeout functions. Currently, they can be cancelled using the clearInterval and clearTimeout functions, and we can use defer to integrate them into a disposable stack:

function main() {
	using stack = new DisposableStack();

	const handle = setInterval(() => {/* ... */}, 5000);
	stack.defer(() => clearInterval(handle));

	// ...
}

In fact, if you’re using NodeJS, you can go one better. The NodeJS timers (i.e. setInterval and friends) already return an object (Timeout) with lots of useful functions like .unref(). Recent versions of v18 and upwards now also include a Symbol.dispose key for these objects, which means you can simplify the above code to this:

function main() {
	using setInterval(() => {/* ... */}, 5000);

	// ...
}

And in the browser, we can write a similar utility function:

export function interval(...args: Parameters<typeof setInterval>): Disposable {
  const handle = setInterval(...args);
  return { [Symbol.dispose]: () => clearInterval(handle) };
}

The Use-and-Move Maneuver

One more subtle but incredibly powerful method in the DisposableStack arsenal is .move(). This creates a new stack, moves all of the resources in the current stack into the new stack, and then marks the original stack as disposed. None of the resources will be disposed except for the original stack.

This is a powerful tool for anywhere where you’re creating resources for use elsewhere (so you want to put them in a stack), but the very act of creating resources is something that might fail (so you want to be using that stack when you create them.

Consider this example, which can cause resource leakages:

export function badOpenFiles(
  fileList: string[]
): { files: File[] } & Disposable {
  const stack = new DisposableStack();
  const files = [];
  for (const fileName of fileList) {
    files.push(stack.use(open(fileName)));
  }

  return {
    files,
    [Symbol.dispose]: () => stack.dispose(),
  };
}

If I call this with a list of files, it’ll open all of those files and return them as single disposable object, that when it gets disposed of, closes all the files again.

But let’s say I call this with the file list ["file1.txt", "file2.txt", "file-does-not-exist.txt", "file4.txt"]. Now, the first two files get created and added to the stack, but the third one causes an error, which exists the function. But because the stack was never added to a using declaration anywhere, those files will never be closed, which causes resource leakage.

The .move() function allows us to do this instead:

export function openFiles(fileList: string[]): { files: File[] } & Disposable {
  // Note we use the stack here, which means this stack will be cleaned up
  // when we return from the function.
	using stack = new DisposableStack();
	const files = [];
	for (const fileName of fileList) {
		files.push(stack.use(open(fileName)));
	}

	// We've successfully created all the files with no errors.
	// Move the opened file resources out of the stack, and into a new
	// one that won't get closed at the end of this function.
	const closer = stack.move();
	return {
		files,
		[Symbol.dispose]: () => closer.dispose()
	};
}

The Disposable Wrapper

Right now, Disposables are still relatively new, and so it’s not unlikely that the library you’re working with doesn’t support them, opting instead for a .close() method or something similar. But Javascript is a dynamic language, so it’s not too hard to get these tools to behave. Here’s an example for MongoDB, which at the time of writing does not support using or any of the disposable protocols:

function createMongoClient(
  connection: string,
  options?: MongoClientOptions
): MongoClient & Disposable {
  const client = new MongoClient(connection, options);

  if (client[Symbol.asyncDispose]) throw new Error("this code is unnecessary");
  return Object.assign(client, { [Symbol.asyncDispose]: () => client.close() });
}

This will add a Symbol.asyncDispose method to the client, meaning you can use it in await using declarations and with AsyncDisposableStack#use(). In addition, if you ever update to a version of MongoDB that does implement the AsyncDisposable protocol, you’ll get an error reminding you to delete the code.

Awaiting Signals

A common pattern for NodeJS servers is to start up the web server, and then add event handlers for the OS’s “quit” signals (e.g. SIGINT). Inside these handlers, we can shut the server down, clean up resources, etc.

This works fine, but the control flow can be difficult to follow, and we have to manually call the Symbol.dispose and Symbol.asyncDispose methods where that’s relevant. It would be nice if there was a way to tie the lifetime of the application to the lifetime of a single function, so that when that function exits, the server will also automatically exit, closing and disposing of all resources along the way.

Enter NodeJS’s once function, which converts an event into a promise¹:

import { once } from "node:events";

// waits until the `SIGINT` signal has been triggered, e.g. from Ctrl-C
await once(process, "SIGINT");

Using this, we can write a main() function that lives for the entire length of the application, and quits when the application is stopped, automatically cleaning up any resources after itself:

async function main() {
  await using stack = new AsyncDisposableStack();
  await using resource = createResource();
  // ... etc, for as many resources as make sense

  // alternatively, use the "Disposable Wrapper" pattern from earlier
  const server = stack.adopt(express(), server => server.close());

  // add routes, use resources, etc
  server.get(/* ... */);

  logger.info("starting application on port 5000");
  server.listen(5000, () => logger.info("application started"));

  await Promise.race([
    once(process, "SIGINT"), // Ctrl-C
    once(process, "SIGTERM"), // OS/k8s/etc requested termination
    // etc.
  ]);

  logger.info("shutting down application");
}

Because all of our resources are managed either by using directly, or by the stack which is in turn tied to the application’s lifespan, we don’t need to manually close anything after the signals have been handled — everything will automatically be gracefully shutdown.

Using Explicit Resource Management Today

Right now, explicit resource management is a stage three proposal — that means that the specification has been completed and approved, and browsers and other tools are encouraged to start implementing the proposal, and trying the feature out in practice².

This means that if you want to try this feature out right now, you’re going to need to transpile the syntax to a format supported by older browsers, and provide a polyfill for the various global objects that the feature requires.

In terms of transpiling, both Typescript and Babel support the using ... syntax. For Typescript, you’ll need version 5.2 or greater to handle the syntax. In the tsconfig.json file, the target should be ES2022 or lower in order to do the transpilation (otherwise Typescript will leave the syntax unchanged), and the lib setting should include esnext.disposable (or alternatively the whole esnext bundle of types) to ensure that the right set of types is included. For Babel, including the stage-3 preset, or explicitly adding the @babel/plugin-proposal-explicit-resource-management plugin should ensure that everything gets compiled correctly.

Neither Typescript nor Babel include a polyfill for the various global types discussed here, which means you’ll also need a polyfill. For this, there are various options, including disposablestack, which I’ve been using, and CoreJS.

Bringing It All Together

Let’s say we’re writing something on the backend, and there’s a lot of interactions with users. We want a class that handles all of our user-based logic:

• It can create/read/update/delete our user objects in the database
• It automatically deletes users that haven’t been active in the last five minutes (we’re very GDPR conscious here, we don’t keep data a second longer than we need to)
• It provides a stream of all the new users inserted into the database, so that elsewhere we can send them a lovely greeting message.

We’ll use dependency injection so that we don’t need to create the database connection ourselves, but some of the resources will be managed by the user service. We can use the AsyncDisposableStack to group those resources together, and we’ll add a Symbol.asyncDispose method that delegates to the stack’s dispose method to handle that disposal. We can even implement Typescript’s AsyncDisposable interface to make sure that we get everything right:

export class UserService implements AsyncDisposable {
  #conn: DB.Conn;
  #stack = new AsyncDisposableStack();
  #intervalHandle: NodeJS.Timeout;
  #streamHandle: DB.StreamHandle;

  constructor(conn: DB.Conn) {
    // Our DB connection, passed in via dependency injection -- so we don't want
    // to add this to the set of resources managed by this service!
    this.#conn = conn;

    // Remember, NodeJS's `Timeout` class already has a `Symbol.dispose` method,
    // so we can add that to the stack
    this.#timeoutHandle = this.#stack.use(
      setInterval(() => this.deleteInactiveUsers(), 60 * 1000)
    );

    // For resources that don't have the right methods, `.adopt()` is the
    // easiest way to add an "on dispose" cleanup function
    this.#streamHandle = this.#stack.adopt(
      this.#createNewUserStream(),
      // Closing this stream is an async operation, hence why we're using
      // Symbol.asyncDispose, AsyncDisposableStack, etc.
      async (stream) => await stream.close()
    );
  }

  async [Symbol.asyncDispose]() {
    await this.#stack.dispose();
  }

  // ... methods and implementation details
}

Now we need to actually construct all of our resources somewhere. We can add a createResources function that creates the resources, returns a disposable object that cleans up all of the resources together, and also ensures that if an error occurs during resource construction, everything will still get cleaned up gracefully — this is the power of the stack!

export async function createResources(config: Config) {
  await using stack = new AsyncDisposableStack();
  const db = new MyDbDriver(config.connectionString);
  const conn = stack.use(await db.connect());

  // When the stack disposes of its resources, the `UserService` will be cleaned
  // up before the `conn`, which prevents errors where the `UserService` is
  // trying to use a connection that doesn't exist anymore.
  const userService = stack.use(new UserService(conn));

  // Now all the resources have been set up, use .move() to create a new stack
  // and return a dispose method based on the new stack.
  const closer = stack.move();
  return {
    userService,
    [Symbol.asyncDispose]: async () => await closer.dispose(),
  };
}

Now finally, we need to plug all of this into our server implementation, and make sure that everything gets cleaned up when the server gracefully exits. We can use signals and promises to catch the events that should trigger a shutdown, and use the using declarations to automatically clean up any resources.

async function main() {
  const config = await loadConfig();
  using resources = createResources(config);
  using stack = new AsyncDisposableStack();

  // create wrapper functions around APIs that don't yet support disposables
  using server = createFastify({});

  server.get(/* route using resources.userService */)

  await server.listen({ port: 3000 })
  logger.info("server running on port 3000");

  // use `once` to turn one-time events into promises
  await Promise.race([
    once(process, "SIGINT"),
    once(process, "SIGTERM"),
    once(process, "SIGHUP"),
  ]);

  logger.info("server terminated, closing down");

  // resources will all be cleaned up here
}

More Resources

There’s a lot more information out there about the explicit resource management proposal, but given how Google isn’t working as well as it once was, here are some links to help you find it:

• The original proposal in the TC39 GitHub organisation. The documentation is a bit technically-focussed here, but the issues provide a lot of good context for the APIs, and a number of examples that explain why certain decisions were made.
• Typescript 5.2’s release notes include a section about resource management, how to use it, and how to get it working in Typescript.
• Various tickets/bugs/issues about implementing explicit resource management:
  • Chrome
  • Firefox
  • Safari
• Prior art in other languages:
  • C#’s using statement is a big influence here.
  • Go’s defer statement inspired the .defer method.
  • Python’s ExitStack is an explicit inspiration for the DisposableStack and AsyncDisposableStack classes.

You can also find an edited and updated version of this post that I wrote for my employer’s blog here.

A discussion came up on Reddit recently about DI, where I mentioned that one way that I’ve done DI recently for web frameworks that don’t naturally support it to using closures. Someone asked for an example, so I figured I’d explain what that looks like and where it might work (or not work). The original question was about Python, but I’ll give Python and Javascript examples.

I’m going to start with some context of my dependency injection philosophy, but if you want to skip that, you can jump straight to some examples here.

Why DI

The problem I’m trying to solve here is DI, or dependency injection. I have a function, class, or in this case route handler that needs access to a given resource, such as a database connection. As I do that, I have three aims:

1. I want to wrap the database connection in an explicit interface to allow encapsulation — I don’t want my routes to have to know how the database is structured, I just want them to be able to load and save e.g. User objects.
2. I want to be able to parameterize the database connection. When I run the code from my local machine, I want it to point to a local database, and when I run the code on production, I want it talking to the live database. That should happen automatically based on configuration files or environment variables.
3. I want to prevent code from having to construct its own dependencies (i.e. I want inversion of control). I don’t want to create the database connection inside the route handler, I want that to happen outside the route and the result be passed to the route handler in some way.

The solution to this is dependency injection, or DI. When I first started programming, this term confused me for a bit, because I’d see lots of “DI frameworks” or similar tools, and I assumed that DI meant the act of using decorators or annotations to automatically inject parameters into the right place. This is not the case — those tools are often useful, but DI is more about how you write your code in the first place. For example, here are two Python functions, one of which uses DI:

import emails

# Function 1

def send_emails(user: User, message: str):
    emails.EmailMailer().send_email(user.email_address, message)

send_emails(User(name="...", email="..."), "this is an email")


# Function 2

def send_emails(mailer: EmailMailer, user: User, message: str):
    mailer.send(user.email_address, message)

mailer = emails.EmailMailer(**email_params)
send_emails(
    mailer,
    user=User(name="...", email="..."),
    message="this is an email",
)

I think this is a good example, because you can see the advantages and disadvantages of DI. In this example, the second function uses DI, and the first function does not. The thing that jumps out the most to me is that the DI example is much more verbose — it takes more code, and it makes function signatures more complicated because they’re taking more parameters. Partly that’s just how I’ve written these examples, but I do think DI adds complexity — useful complexity, but complexity nonetheless. You don’t need DI if it’s not adding value.

However, there are some benefits visible in the second function. By making the EmailMailer object explicit and bringing it out of the send_emails function, we can now more easily pass parameters to it. If multiple functions are all using the EmailMailer object, and we need to change how we configure it, then now we can do that configuration in one place, rather than at every place that it’s used. (Alternatively, before we might have used some global configuration, but with DI, we can be more explicit.)

We can also swap out the mailer object that we use. I think this is often oversold as an advantage (how often do you really swap out implementations like this?) but it’s often useful for testing. If we want to test the first send_emails function, we’d have to mock a bunch of global imports, but with the second, we can just call the function with a mocked parameter.

The most important thing to notice here is that Function 2 uses dependency injection without going near a DI framework — without even using a single decorator! At its core, DI is just moving things from being constructed inside functions, to being constructed outside functions, and then figuring out how best to pass them back in.

Note that I’ve used functions here, but classes work in much the same way. Typically, parameters can be passed to the class constructor (__init__(), constructor(), etc), and then attach as instance attributes (self.param, this.#param, etc). I’m not going to use that style in this example, but I often use it for service objects.

With that out of the way, this is a way of doing DI via closures.

DI & Closures

Here’s a couple examples of route definitions in FastAPI/Python and in Express/JS:

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id):
    # ... TODO: get item value from a database somewhere
    return {"value": ...}

import express from "express";
const app = express()

app.get("/items/:itemId", (req, res) => {
  // ... TODO: get item value from a database somewhere
  res.json({ value: /* ... */ });
});

As discussed above, dependency injection is about passing parameters to functions. But in the two functions here, that’s difficult, because the parameters are fixed, and we don’t actually call the functions. For example, with the Express example, Express will always call our route handler with the req and res. There’s no place to inject any services or dependencies of our own.

One option might be to attach our dependencies to the parameters. This is common in Express, where middleware can be used to dynamically add a req.users or req.conn attribute that can be accessed inside the routes. However, this can be error-prone, not least because it isn’t compatible with Typescript unless you start modifying global types.

An easier option, at least for simple cases, is often just to use closures to capture the dependencies. Here are some examples to show what I mean:

from fastapi import FastAPI

app = FastAPI()

def add_routes(app: FastAPI, *, item_store: ItemStore):
    @app.get("/items/{item_id}")
    async def read_item(item_id):
        item = await item_store.load(item_id)
        return {"value": item.value}


item_store = ItemStore(db=...)
add_routes(app, item_store=item_store)

import express from "express";
const app = express();

function addRoutes(app: Express, itemStore: ItemStore) {
  app.get("items/:itemId", async (req, res) => {
    const item = await itemStore.load(item_id);
    res.json({ value: item.value });
  });
}

const itemStore = new ItemStore(db);
addRoutes(app, itemStore);

The basic idea is that we move the route definitions from being defined at the top-level to being defined inside a function. The inner functions are now closures — when the function is called, the inner functions will have access to variables defined in the outer scope (in this case the parameters), and so can access the dependencies they need. We can then create all the dependencies, as well as the main app beforehand, and pass them to the addRoutes function.

In practice, I often have a create_context() function that loads configuration from somewhere, creates all the dependencies, and returns Context object or typed dictionary which contains all of the dependencies with keys. Then I can pass that whole context object to builder functions like add_routes(), rather than specifying all the dependencies individually.

Sometimes I also move the app = FastAPI()/const app = express() line inside the builder function, and have it return the entire app. I don’t think one is better than the other, and which I use depends mostly on my mood.

Where This Works Well, or Doesn’t

I’ve used web routing as an example here, but I find this works well enough in any situation where I can’t easily pass something in via function parameters. Most languages I use — even quite static ones like Rust — allow functions to be defined within other functions like this. The key requirement is good support of closures, but this is also fairly standard at this point.

There is an issue if you also want to export the functions somehow. With the FastAPI example above, if we wanted to import the read_item function somewhere else and call it, that becomes very hard with closures. In this case, that’s not a problem, but I’ve run into contexts where it’s more of an issue. In cases like that, I try to decouple the function entirely from any dependencies it needs, and just pass in raw data.

I’ve also noticed that this can be harder to implement correctly in some cases with Rust, if the lifetimes don’t match or the type is difficult to name correctly. Typically Rc/Arc + Clone for services solves most issues, and sometimes boxing up the return value is necessary.

Alternatives

Of course this isn’t the only way! Here are some other options that I also have in mind when deciding how to get my dependencies injected.

• No dependency injection at all — I find this works really well up to a point, and then it stops working fast, usually around the point I’m configuring multiple DBs/external services, and want to get everything running in multiple environments. But simple is better the complicated, and no DI is simpler than DI.
• Using module-level values. In Javascript, for example, I can export a value, as in export const USERS = new UserService(). Similar things are possible in Python and most other more dynamic scripting languages. This can be used instead of DI, and most languages have some way of mocking static module exports, so you can still swap in test implementations. But I find this often ends up quite hacky, and the dependency nest can get quite deep, so I try to avoid this these days.
• A lot of frameworks provide some kind of app context field or value, which can be dynamically updated with different services or connections. Personally, I find it hard to keep track of what’s on the context and what isn’t, and I’ve rarely found a simple way of handling this when I’m using types.
• FastAPI has something it calls DI, but is really just request extractor — it is called for each request, it is passed the request, and it extracts the details it needs. I personally haven’t had much success using this feature for DI proper. That said, other frameworks do provide a full DI framework. If it’s built into the framework, then I tend to follow the “when it Rome, do as the Romans” principle.
• If all else fails, there are lots of DI libraries. I tend to avoid these, because it’s added complexity when just passing in functions works well enough. But sometimes you get to the point where constructing all your services and dependencies up front doesn’t cut it, and you need something more powerful. I’ve not reached that point myself, but most of the projects I’ve worked on have been relatively small.

Conclusion

I hope this was helpful, this is just one strategy that I’ve found useful for doing simple DI without having to lean into frameworks or have annotation/decorator-based magic.