tl;dr; in the modern TS/JS landscape and overall tooling trends, better stick with static code generators, they are more performant in many ways, easier to integrate into apps, other tools and the multitude of modern JS runtimes. My new tool is as good as other static code generators, but it also produces strictly type safe code and unit tests for you.

This post goes into a rather deep comparison of my new tool Type Predicate Generator (from here just Generator) to other runtime type checkers, also giving a rather broad overview of the related topics. To get a sense of what it does try checking the Playground first.

If you're about to create your first tool for the TypeScript ecosystem the insights in this article will help you hit the ground running.

Comparing Generator to the pure runtime checkers

The most popular library in this category is the infamous zod.

Type checkers in this category use only the code that the JavaScript engine runs within an application. No type information is used inside of this class of libraries. Some of them use eval to turn a schema into JS code at runtime, some like zod use pure function composition.

Generator produces code that is over 100 times faster

Check out the benchmark results.

Like for the most other code generators for (including other dynamic JITed languages) the main reason is that Generator produces specialized code that is easy for all the modern JS engines to optimize. Each type predicate function consists of trivial instructions (like typeof x === "string" and x === "constant") that in most cases don't even call any other functions and never any external or shared functions. JIT JavaScript engines like when code types are local and when for each distinct type there is a separate small function. This helps JS engines to specialize these small functions in runtime. See this amazing article for more details on how V8 deals with polymorphic functions.

Pure runtime checkers like zod instead use function composition. In this case, basic building block functions (like hasProperty(object, propertyName)) get reused with values of different types and thus different hidden classes. This leads to frequent deoptimizations (falling back to the slower non-optimized byte code instead of the faster native code). In the most severe cases, the JIT compiler might oscillate between optimizing and then deoptimizing a code path for one type and then another, spending a lot of cycles in just compiling the code instead of actually running it.

Generator does not have any runtime dependencies

The code emitted by a tool like Generator that gets into the bundle is the exact code you see in the git diff output in your project after generating the type predicates. The only other code the predicate uses is the built-ins like Array.isArray() (safely wrapped!). This means that the bundle real estate Generator uses for the predicates stays minimal. It grows linearly with the size of types. The net amount of code used to define a Zod type is comparable to the size of an average predicate after minification.

Purely runtime type checkers by design are a runtime dependency. They require the runtime library of matchers to be included in the resulting bundle. Most of the libraries use handy constructors that are flexible enough to allow most of the checks a general API would need. This is great, but also affects the bundle size (60+ KB for zod) because the more generalized matchers cannot be tree-shaked statically (here is an interesting attempt on dealing with the bundle size).

Another emerging issue with the runtime-only complex libraries that are used in performance and availability-critical parts of the application is compile-time compatibility with the WinterCG runtimes. Heavy runtime libraries tend to target feature-rich runtimes like Node and throw in runtime for corner cases like error message generation, requiring more testing. This is not an issue if you're on a widely supported platform like Node or the latest browsers, but if you're investing in, say, Wasmer Edge, adding a seemingly trivial dependency might turn into turmoil.

Generator produces TypeScript code that is strictly type-safe

This is one of the key distinctive features of Generator. The code produced by Generator that gets into your app bundle first gets checked by your app's TypeScript setup to verify it's safe internally and matches the types being checked. Generator plays well here by producing strictly type-safe code that is going to compile even in the strictest configurations. What is also handy is that when you make a change to the type that has a generated predicate, the tsc reminds you to update the predicate too (by just re-generating it).

The purely runtime checkers cannot directly use the power of TypeScript to verify that the composed function has all the required checks in the right order. Even a proper TypeScript type predicate that does not use at least the satisfies type operator can easily fool itself by just returning true for any input value without making sufficient enough checks.

function isUser(value: unknown): value is User {
  return true; // TypeScript blindly trusts us here
}

Of course, the production-ready libraries like zod use TypeScript internally to check the library's code correctness and provide utility functions to infer types from the runtime building blocks. This helps with improving the code reliability by far compared to some purely JavaScript libraries. But even this still does not let the tsc of your project verify the final code correctness on its own. There is always some wrapping/linking/helping code that cannot be verified.

Generator produces code that is readable and modifiable

Here Generator stands out once more. For the cases when there is a blocking feature that the generated predicate does not support or there is a bug in it that requires urgent fixing, the code produced by Generator is readable and can be immediately edited. As the type predicate code does not change often, there would be no pressure to send patches upstream to the Generator source code (even though highly appreciated!). Such a quick fix would be trivial to review in a tiny PR and remain local to the predicate in question, allowing the team to unblock without any sync dependencies on the Generator's development process.

In the case of a runtime library, a fix would require a patch to the library itself to be able to mitigate the issue. Such a patch would touch all the code that is checked by the library and require more thorough testing. A short-lived fork might be an option here, but would require finding out how to run the build and publish pileline of a given tool.

Generator does not require defining types using a custom DSL

Generator takes in a TypeScript type defined in any part of the application using just native TypeScript. Even a type from a third-party library or a different team's public type that doesn't use any runtime type checker. It's just types, everything is compatible, and composable. Some other tools might even omit calling into the TS API and just parse the types themselves, this makes the tool a bit less flexible but provides a boost in compiling performance.

Contrary to this, by design, all of the runtime checkers provide a set of classes or functions that form the final type checker instance that is used to check the values. Most of them require inferring the resulting type from the resulting compound function. This effectively turns the runtime generators into DSL-first libraries (popular in the Ruby world) instead of being truly TypeScript first. This way, the focus shifts to a more schema-centric approach of consuming APIs where TypeScript is more of a powerful secondary tool than a primary target.

Generator produces code that is way faster to cold start

This is by design of any code generating tool; the generated code is simply more performant to deal with for JS engines. JS engines have developed lots of tricks to make the initial parsing as fast as possible, especially including lazy parsing. The code that Generator produces is native for such optimizations as it's no different from any other production code that constitutes the rest of your app. It is also trivial to three-shake.

The runtime checkers approach by design requires some code to be run at the startup that forces the JS engine to parse, compile, and execute the library code no matter if the predicate is going to be used or not right away. It is possible, though, to wrap the runtime checkers in factory functions to mitigate the issue, but the runtime library code still has to get into the bundle and get parsed at the startup.

Note that there are JavaScript runtime environments that rely on heap snapshots (V8 snapshots, WASM-based JS engines) that allow you to make a snapshot of the JS engine memory after the app has been initialized. If this reminds you of a preforking network daemon, then it's a really close analogy. These environments can help with significantly improving the cold start times for the runtime checkers but still at the expense of more memory usage as the final checker function has to be constructed in the heap even when not used.

Generator does not use eval()

Generator like every other code generating tool compiles the predicate code during the build step and does not require eval() and friends that are not available in high-performance and secure runtimes like Vercel Edge Runtime, AWS CloudFront, Cloudflare Workers and Akamai EdgeWorkers.

The runtime checkers that use eval() and friends in runtime to allow for the JIT optimizations introduce even more steps for the JS engine to make before the actual code of a type predicate can be run. The eval() approach requires the library to build a predicate source code as a string, usually combining it out of smaller strings that then have to be garbage collected, told the JS engine to parse it, and only then executed. While flexible, this approach introduces additional startup latency, memory consumption, and overall more demanding requirements to the runtime environment.

I should mention here that using eval() is a potential security issue. The resulting artifact can be considered by security audit tools as potentially vulnerable. Honestly, it should not be a real issue in the case of a type checker library, especially if the used library source code is frequently audited and comes from a trusted source.

Easier debugging and better stack traces

Every library from time to time introduces or reveals a bug. With Generator as a static code generating tool, the source code that might raise an exception is explicitly bundled with your app and covered with source maps. Using a step debugger on the generated code is the same experience as stepping through your own app code. The stack trace in the error reporting tool is going to be crystal clear too. Such a bug can rarely happen within a code like that Generator produces, but it's still possible, e.g. when a Proxy object throws on property access or a getter returns an unexpected null, or a library misuses patching global prototypes.

A runtime library in most cases would produce a stack trace with minified symbols. This is especially visible if used with the new native support for TypeScript in Node.js, where there are no source maps in use at all.

Native IDE experience

Generator's code is trivial to navigate to through every IDE's "goto definition" feature. Like with every developer focused code generating tool (like TypeScript itself) the hover types are also just the exact types used in your application, no added wrappers or renaming. Plus, the actual code of the type predicate is available a click away in case you'd need to modify it.

In the case of zod, you'd see the inferred types that cannot have other neat features like type-level JSDoc (property-level JSDoc works though) or type-level generics (runtime workaround exists but requires some effort).

Generator produces code that is easy to review

Another benefit of having explicitly generated code version-controlled in your repository is that it's trivial to audit. Starting with all the changes immediately visible during PR review through GitHub-based code scanners. This also makes upgrading the Generator package trivial as all the changes the new version introduces into the generated code are immediately visible in the project's git diff and are covered by the generated unit tests.

For the sake of completeness on the topic of safety and touching a bit the supply chain security, the users of a runtime library are still running a compiled-to-JS source code of the runtime checker that can theoretically be anything as the *.d.ts files don't provide post-build verification for the *.js code that comes in the library bundle. So, for more safety and security-strict applications, the ability of having the actual code verified by the project's set of security tools can be important.

Comparing to TypeScript compiler plugins

The most popular and feature-rich tool in this category is Typia.

The type checkers in this category generate the type predicates code during the build step. They hook into the tsc compiler as plugins and provide type-level helper types that get transpiled into the actual JavaScript code during the code generation stage of the tsc compilation pipeline.

Generator does not require tsc plugins

Generator by design is a standalone tool that has its own TypeScript version bundled inside that does not interfere with your app's TypeScript setup. Even if Generator breaks during an upgrade, the predicates code it has generated is already checked into your repository and is not going away. The code is rather static and does not strictly require Generator to even be part of the build pipeline; you can simply code the code from the Playground.

As TypeScript does not officially support plugins for tsc, the checkers that rely on hooking into tsc require patches to tsc itself. This is a blocker for most teams that want to run a vanilla TypeScript compiler for different reasons. Mostly, it's reliability as TS is the safety net that proves the code will work in production.

Another issue with having tsc plugins is that major TypeScript updates tend to introduce breaking changes to the internal APIs. In an optimistic case, just breaks the plugins and errors out. In a more tricky case, the plugin is going to continue working but might produce invalid code. This, in its strictest form, requires the app developer to wait till all the plugins have upgraded their TypeScript support, upgraded their test suites, and published the updated package. In projects with strict SLAs, this might also require waiting some time till the community adopts the freshly published package.

I have to admit that tsc plugins provide elegant APIs that I personally like the most as a programming language enthusiast. But strictly speaking, TS plugins extend the language as a whole and are not in line with the course TypeScript and the rest of the community (see reasoning and comments here) has been taking for a long time. A bit sad, but otherwise, we would have gotten another JS fork (like CoffeeScript or Facebook's Flow) by now.

Generator produces type-safe TypeScript

As mentioned above Generator produces TypeScript code that is strictly type safe and is checked by your tsc setup according to the safety rules of your project.

The TS plugins instead produce JavaScript code that is not type checked by the TypeScript compiler, meaning that this part of the code that your project runs is still purely JavaScript even though coming from the TypeScript compiler. Of course, the tool creators test the output code really well, but you still have to outsource the type safety to the external tool build pipeline.

Generator code is explicitly readable and modifiable

As mentioned above Generator produces code that is readable and modifiable

To check what a tsc plugin-based checker actually produces, you'd need to extract the generated code from the compilation pipeline. That code is purely JavaScript, which would require you to manually check the produced code's correctness.

The fact that the produced code is in most setups not checked into the repository makes the package upgrades a multi-step process. To make sure that the new version of the plugin-based checker produces comparable code, you'd need to save somewhere the current emitted code, upgrade the package, and run a diff. With Generator, this comes out of the box.

The only downside of that Generator produces files is the explicit build step. With a tsc plugin, there is no code to worry about; the plugin keeps the predicates always up to date. Still, not all the build and development tools support hot reloading with full tsc plugin support (example issue that took almost a year to fix).

Generator code is shareable across project boundaries

It's just a tiny TS file that any JS ecosystem tool can consume as is, along with the rest of your application code. You can even just copy it from the Playground.

If you needed to share your TypeScript source code that uses tsc plugins with other teams, you'd have to first publish it. This requires compiling the code down to a JavaScript bundle and publishing along with the *.d.ts files. Another way is to make other teams use the same set and versions of tsc plugins, including the checker plugin in their setup too. This requires some coordination and might slow down migrations to the newer TypeScript versions. Another blocker might come from the teams that are not building their project with tsc and instead use the new tools that natively understand TypeScript syntax and do not require a separate build step (Node.js native TS support, esbuild, Cloudflare wrangler).

Generator emitted code is easy to debug

As mentioned above in Easier debugging and better stack traces, Generator emits code that is friendly to debuggers and error reporting tools. The stack traces are native to your application, giving instant feedback on where the error originates from (both the validation errors and potential runtime errors).

In the tsc plugin case during debugging and reading stack traces, the source maps are going to point only to the single symbol in the source TS code (in most cases, the is token). In case of an issue or a bug with the source code or the checker itself, it's required to inspect the raw JavaScript bundle instead.

There is a workaround though. It should be possible to publish both source maps for your app's bundle and for the dependencies and set the error reporting tool up to look for the source maps there. Quick googling did not show definitive results on how to deal with transitive source maps though.

Generator supports all the JS/TS tools

The statically generated predicate code is easy to use with the new Node.js TypeScript strip feature. No need to use ts-node or precompile the code with tsc. The same applies to the various test runners and edge runtime bundlers.

With a tsc plugin, you're locked within the tsc-centric infrastructure. It's not something particularly challenging but might require additional setup and degrade performance. For example, Vite transpiles *.ts files 20-30x times faster with the default esbuild compiler than with tsc. The new super fast ts-blank-space package does not even run TypeScript type analysis that is required for tsc plugins to work and, through this, is also blazing fast.

So, once again, extending the type system that affects resulting syntax effectively turns this category of checkers into a language extension.

Comparing to the other code generators

The most complete (and dear to my heart as I've used it in the past) tool in this class is ts-auto-guard.

This class of checkers produces the final predicate code as distinct files that should be explicitly imported into the application code and built with the rest of the code. Generators fall into this category of runtime type checkers.

Most of the arguments above in favor of using Generator more or less apply to all of the tools in this category.

Generator produces type-safe TS

As mentioned above, Generator produces TypeScript code that is strictly type-safe

Other code generators that also produce TypeScript at the moment of writing emit code that is not type-safe. The not-safe emitted code uses unsafe constructions like type casting (with as) or can rely on the unsafe types (mostly any). This effectively turns the produced TypeScript code into loosely typed JavaScript. If your application's setup uses strict TypeScript linters, the produced code would require adding exceptions and lower the overall type safety score.

Generator produces readable code

As mentioned above Generator produces code that is readable and modifiable. In addition to this, compared to other code emitting tools, Generator helps you with reading, debugging, and potentially manually changing the generated code by linearizing all the checks. It makes small steps that are easy to navigate and adds comprehensive comments (coming soon!). This means that the produced code is not minified but is still organized in the way that common bundlers minify can easily turn it into a tiny combined if expression anyway. Generator also tries to use meaningful local variable and temporary type names where possible to improve the reading experience.

The code produced by most of the other tools in this category is pre-optimized and thus not really readable. This gives better control to the tool maker to achieve the best performance as not all the bundlers can infer how to deal with rather complex predicate functions for the more complex types.

Generator always produces correct code

As the code Generator emits is strictly checked by the TypeScript compiler and also is emitted using the TS AST builder API (see the awesome ts-ast-viewer.com to play with the API). This makes it impossible for Generator to produce invalid TypeScript.

During my research, I've found that for some nontrivial cases, other checkers that use string concatenation can produce invalid or incomplete code. Luckily, the invalid code is immediately rejected by the TypeScript compiler (this is the superpower of the code-generating tools in general), but the incompleteness is not covered as the produced code is not type-safe. This also applies to checkers that rely on eval() at runtime.

Generator code is fast

Small disclaimer here. Most of the type-to-code generators show significantly (100x) better performance than purely runtime solutions and sensibly better startup times compared to those that use eval. But Generator still has some tricks up its sleeves.

What Generator adds to the table is accessing object properties only once, broadly reusing local variables, that makes the code extremely fast even in non-optimizing JS engines (this traces back to the techniques used to make old JS engines faster). Also, this trick potentially simplifies analysis for the modern JS engines.

Most other checkers form full or partial nested property access expressions that take some time for the JS engine to identify and optimize as it's just more bytecode to analyze:

function isUserProperties(v) {
  // …
  return typeof v.a.b === "object" &amp;&amp; v.a.b !== null;
}

// node --print-bytecode --print-bytecode-filter=isUserProperties bytecode.js
// GetNamedProperty a0, [0], [0]
// Star0
// GetNamedProperty r0, [1], [2]
// TestTypeOf #7
// JumpIfFalse [13] (0x22bd65001e68 @ 24)
// GetNamedProperty a0, [0], [0]
// Star0
// GetNamedProperty r0, [1], [4]
// TestNull
// LogicalNot
// Return

function isUserLocals(v) {
  // …
  const b = v.a.b;
  return typeof b === "object" &amp;&amp; b !== null;
}

// node --print-bytecode --print-bytecode-filter=isUserLocals bytecode.js
// GetNamedProperty a0, [0], [0]
// Star1
// GetNamedProperty r1, [1], [2]
// Star0
// TestTypeOf #7
// JumpIfFalse [6] (0x5e08e641f02 @ 18)
// Ldar r0
// TestNull
// LogicalNot
// Return

There is no second GetNamedProperty in the local variable code. It uses one more register, though.

Generator also tests the generated code

As a bonus, during the predicates generation, Generator can also optionally emit a load of unit tests for the generated predicates. You can run these tests as part of your application's test suite.

At the moment, this is a rather unique feature that I hope is going to be picked up by other tool makers. Read more about the approach here.

Summary

That's it folks! You can play with Generator in the Playground.

An in-depth comparison of the three main kinds of runtime type checkers to my new tool