Estimate project
← All posts

A new approach to building TypeScript libraries that are both ergonomic and tree-shakable

A clever approach to building tree-shakable TypeScript libraries that doesn't sacrifice the user experience.

10 min read
type-level programmingtypescriptlibrary

This article walks through a clever approach to building tree-shakable TypeScript libraries that doesn’t sacrifice the user experience.

The big picture looks like this:

  • Users access our library’s API via one entry point (think Zod).
  • Thanks to that, they can rely on techniques like method chaining, the builder pattern and so on.
  • Before using this entry point, though, they have to initialize it by explicitly importing the functionalities they want. Every additional functionality they import extends the API and increases the final bundle size.
  • As a result, the library author can ship more features without fearing a bloated public API, since the user is the one who chooses which APIs get enabled and bundled.

To grasp this idea better and see how it can be implemented, let’s examine a concrete example.

Take Zod, a widely used TypeScript-first schema validation library. Developers love working with it, and it has a rich ecosystem.

This is how it’s typically used:

import { z } from "zod"; // 12.8 kB

const LoginSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

// Throws error
LoginSchema.parse({ email: "", password: "" });

// Returns data as { email: string; password: string }
LoginSchema.parse({ email: "jane@example.com", password: "12345678" });

Ergonomics is one of Zod’s biggest strengths. It provides an intuitive, concise interface for building schemas by chaining together methods that don’t mutate anything.

In terms of developer ergonomics, an API that supports method chaining has one major benefit: API discovery. As soon as you type “.”, your IDE shows every possible operation you might want, together with its exact types.

There is a catch, however: the static import size. Using Zod begins with importing a single z object and building from there. Consequently, whenever we use Zod for anything at all, we have to import every available method. Whether we call .brand, .superRefine or .passthrough or not, they all land in our app’s bundle, because Zod isn’t tree-shakable. What exactly does that mean, though?

What Is a Tree-Shakable Library?

Put briefly, tree shaking is the removal of unused code. JavaScript bundlers achieve it by analyzing import and export statements and working out which exports go unused. Tree shaking applies not just to code modules in your own source code but to all of your dependencies as well.

Not every library can be tree-shaken. To be tree-shakable, a library has to be organized in a particular way.

Example of a Tree-Shakable Library Structure

Look at this example:

// `tree-shakable-lib`

export const fun1 = () => "fun1";

export const fun2 = () => "fun2"

If your app then looks like this:

import { fun1 } from "tree-shakable-lib";

console.log(fun1());

the resulting bundle will be:

const fun1 = () => "fun1";

console.log(fun1());

As you can see, the definition of fun2 was left out of the bundle, which makes it smaller.

Example of a Non Tree-Shakable Library Structure

Next, look at this example:

// `non-tree-shakable-lib`

export const lib = {
    fun1: () => "val1",
    fun2: () => "val2"
}

If your app then looks like this:

import { lib } from "./non-tree-shakable-lib.js";

console.log(lib.fun1());

the resulting bundle will be:

const lib = {
    fun1: () => "val1",
    fun2: () => "val2"
};

console.log(lib.fun1());

Here, although only the fun1 method is used, the entire lib object has to go into the bundle, since the bundler cannot safely pull out just one part of an object or a class.

Tip: The Rollup REPL lets you play with tree shaking online with ease

The above is only a short introduction to the broader subject of tree shaking, but it’s enough for the purposes of this article.

Valibot = Zod with Tree Shaking?

Now that we know how to build a tree-shakable library, how could we make Zod tree-shakable? A recently released library named Valibot has made an attempt.

This is what our earlier Zod example looks like after rewriting it with Valibot:

import { email, minLength, object, parse, string } from 'valibot'; // 0.85 kB

const LoginSchema = object({
  email: string([email()]),
  password: string([minLength(8)]),
});

// Throws error
parse(LoginSchema, { email: '', password: '' });

// Returns data as { email: string; password: string }
parse(LoginSchema, { email: 'jane@example.com', password: '12345678' });

The API seems familiar, but it leans more towards a functional style:

  • Rather than calling a parse method on the LoginSchema, we call a standalone parse function and pass the schema as an argument.
  • Rather than dot-chaining extra constraints onto the string validator, we pass them in as arguments. Every constraint is a function imported separately.

This matches the simplified rule for tree-shakable libraries: a library that exports a set of pure functions is most likely tree-shakable. And that’s true for Valibot. Look at the import size noted in the comment on the first line – it’s 15 times smaller than Zod’s, while doing exactly the same job. Naturally, the import size will increase as your app uses more functions, but in practice it’s rare to use 100% of a library’s functionality, particularly with versatile ones such as Zod and Valibot.

Valibot does have one issue, though. Its functional API makes the library tree-shakable, but I’d say that here it also risks making the API less ergonomic. Ergonomics are harder to reason about than import sizes, since they’re more subtle and may come down to personal preference. Even so, I believe Zod’s developer-friendliness makes it superior. These are a few downsides of Valibot’s API:

  • You can’t easily explore the API without stepping outside the IDE.
  • Building each schema means either jumping from the schema definition up to the import statement to add new functions, or listing all of them beforehand.

Correttore: The Best of Both Worlds

A quick recap of what we’ve covered:

  • Zod offers excellent developer experience (DX) but cannot be tree-shaken.
  • Valibot can be tree-shaken, but its API might be considered less ergonomic.

This raises a simple question: could we build a library with the same API as Zod that is somehow tree-shakable as well? Yes, we can – and that’s precisely what the technique I’m about to show is about. As a proof of concept, I built Correttore:

import { email, minLength, object, initCorrettore, string } from "correttore"; // 0.54 kB

export const c = initCorrettore({
  string,
  email,
  object,
  minLength,
});

const LoginSchema = c.object({
  email: c.string().email(),
  password: c.string().minLength(8),
});

// Throws error
LoginSchema.parse({ email: "", password: "" });

// Returns data as { email: string; password: string }
LoginSchema.parse({ email: "jane@example.com", password: "12345678" });

In more detail:

  1. On the first line, we import initCorrettore together with every “piece” of the API our app is going to use.
  2. We call initCorrettore to create a c variable and export it. This c plays the role of Zod’s familiar z. Anywhere else in the app, we’d simply import c from this file.
  3. We build a LoginSchema in what looks like exactly the Zod way, only using our c object. The difference is that while chaining methods, we only see those we imported earlier and passed into the initCorrettore function. For instance, removing email from the initCorrettore call would make the email method vanish from string(), and the schema object would trigger a compile-time TypeScript error. Conversely, importing and adding, say, a number validator would make it show up on the c object as a valid method.

Everything else works as in Zod, yet the import size is only a little over 500 bytes – 25x smaller!

What’s the Secret Sauce

Writing a library like this takes only two ingredients:

  1. Proxy objects
  2. A bit of type-level programming.

Proxy

Proxies let you intercept and redefine the fundamental operations of any object. In the example below, we wrap someObject in a proxy so that each property access gets logged along with the property’s name.

const someObject = {
    a: 100,
    b: "hello"
}

const proxyObject = new Proxy(someObject, {
    get: (target, prop) => {
        console.log(`property ${String(prop)} was called!`);
        return target[prop as keyof typeof target];
    }
});

proxyObject.a; // logs: "property a was called!"
proxyObject.b; // logs: "property b was called!"

In the proxy handler (the second argument passed to the Proxy constructor), we can do pretty much anything. Take a look at the MDN Web Docs on Proxy for more examples and a complete overview of the API.

The core idea, then, is this: when the user initializes Correttore with a record of parsers (like number, string, boolean and so on), we build a proxy from an empty object and just run the parsers dynamically whenever they’re called:

// NOTE: the code below works, but for now, the `c` object is typed as `any`

// mocked parsers for brevity
const string = (x: any) => `${x} is a string`;
const number = (x: any) => `${x} is a number`;
const boolean = (x: any) => `${x} is a boolean`;

const simplifiedInitCorrettore = (parsers: Record<string, (arg: any) => string>) => {
    return new Proxy({} as any, {
        get(target, key) {
            if (key in parsers) {
                return (args: any) => parsers[key as any](args);
            } else {
                throw new Error("Unknown parser");
            }
        }
    })
}

const c = simplifiedInitCorrettore({
    string,
    number,
    // we purposely omit boolean parser here
});

console.log(c.string("hello")); // -> "hello is a string"
console.log(c.number(42)); // -> "hello is a string"
console.log(c.boolean(true)); // -> Error: Unknown parser

The implementation above illustrates the general concept but doesn’t yet support method chaining or correct typings.

To enable method chaining (e.g., c.string().email()), we’ll introduce a parsersChain variable that holds every parser in the method chain (*). So, for instance, c.string().email() maps to [stringParser, emailParser]. Only when .parse gets called do we loop over all the parsers and check the argument against each of them (**).

const createParserProxy = (
  p: Parser<any>,
  parsers: Record<string, (...args: any) => Parser<any>>,
  parsersChain: Parser<any>[]
) =>
  new Proxy(p, {
    get(target, key) {
      if (key === "parse") { // (**)
        return (arg: any) => {
          parsersChain.forEach((p) => p.parse(arg));
          return target.parse(arg);
        };
      }
      if (key in parsers) {
        return (args: any) =>
          createParserProxy(parsers[key as any](args), parsers, [
            ...parsersChain, // (*)
            parsers[key as any](args),
          ]);
      } else {
        throw new Error(`Unknown parser ${key as string}`);
      }
    },
  });

export const initCorrettore = <
  Parsers extends Record<string, (...args: any) => Parser<any>>
>(
  parsers: Parsers
): calculateCorrettoreType<keyof Parsers> => {
  return new Proxy({} as calculateCorrettoreType<keyof Parsers>, {
    get(target, key) {
      if (key in parsers) {
        return (args: any) =>
          createParserProxy(parsers[key as any](args), parsers, [
            parsers[key as any](args),
          ]);
      } else {
        throw new Error(`Unknown parser ${key as string}`);
      }
    },
  });
};

The implementation is full of any types, yet the resulting c object is typed correctly thanks to the as calculateCorrettoreType<keyof Parsers> snippet.

Type-Level Programming

This is the point where type-level programming enters the picture. You have to write a type that mirrors the provided record of imported parsers. For the most part that’s simple; the tricky bit is making it behave so that, say, the email parser is available only after the string() parser and not, for instance, after number().

// Full correttore type with all parsers and extensions
type FullCorrettore = {
  // StringParser is an object that includes the `parse` method as well
  // as all the other parsers that can occur after `string()`, for example
  // `email` or `minLength`. 
  string: () => StringParser;

  // Similarly for this one.
  number: () => NumberParser;

  // see ObjectParser implementation here:
  // based on the object parser from the author's proof-of-concept library
  object: <S extends Record<string, Parser<any>>>(schema: S) => ObjectParser<S>;
};

// given the list of imported parsers and validator, calculate a type for the correttore object
type calculateCorrettoreType<
  features,
  parser extends Record<string, (...args: any[]) => any> = FullCorrettore
> = {
  [k in Extract<keyof parser, features | "parse">]: k extends "parse"
    ? parser[k]
    : (
        ...args: Parameters<parser[k]>
      ) => calculateCorrettoreType<features, ReturnType<parser[k]>>;
};

Summary

The technique shown in this article clearly pays off in user experience and bundle size optimization – but does it come with any downsides?

For the people consuming the library, hardly any. Someone might say that initializing the library is an additional step, and that when the user doesn’t mind the import size (as in server-side applications), it only adds complexity. This can be addressed, though, by exporting an extra pre-initialized object from the library that exposes the full API.

Since this technique optimizes for the user experience, it makes life harder for library authors. For one thing, wiring all the pieces together with a proxy is usually simple, but it means writing code that isn’t type-safe and is littered with any. For another, giving the library consumer correct typings can demand some serious type gymnastics, which may feel intimidating to programmers new to type-level work.


I’d love to hear your thoughts on this – leave a comment below.

If you’d like to help get this project production-ready, you’re welcome to open a PR with changes that move it closer to an API that is 1:1 compatible with Zod.