kdts

A TypeScript compiler with type-driven optimizations

kdts is an optimization-first TypeScript compiler. Instead of erasing types as early as possible, it uses them throughout the compilation to direct optimizations, achieving transformations that would not have been possible were the types not known.

In our codebase, this produces frontend output that is about 40% smaller than the best type-unaware alternative. kdts gets its best results when your code is fully and accurately typed.

Install

bun add -g @kimlikdao/kdts

Currently, kdts is Bun only. If you don't have Bun, install it using npm i -g bun (or see bun.com for other ways to install).

Two modes

To make gradual onboarding possible, kdts has two modes: opt and fast.

• The fast mode is a wrapper around bun build, providing the same set of command line parameters as opt mode. It is fast and works with any codebase. It doesn't check types and produces a larger output.

• The opt mode uses a special fork of Google Closure Compiler (gcc) as a backend. Currently, opt mode supports only a subset of TypeScript, and more features and fixes are being added actively. There are also intentional differences from tsc and even TypeScript itself: in kdts classes and interfaces are nominal types whereas object types are structural; see Nominal and structural types.

Usage

Compile any program with

kdts entry.ts --fast

This will crawl all transitive dependencies (up to the npm package boundary), compile them into a single es6 module and write it to entry.out.js (for other output file names -o other.js). By default, the npm packages are not bundled but left as es6 imports (corresponds to --packages external mode of common bundlers).

To compile a fully typed program in the opt mode, use

kdts entry.ts

Even though npm packages are not bundled, in the opt mode, kdts still needs to discover type declarations for the used packages for the compilation to succeed (by contrast, no type information is needed in fast mode)

To compile and then run a program, test or benchmark,

kdts run entry.ts # --fast mode available
kdts test some.test.ts # --fast mode available
kdts bench some.bench.ts # --fast mode available

For more info about the CLI, use kdts --help.

Experimental status & other caveats

kdts was built to compile our own codebase as efficiently as possible; and in particular our TypeScript library kimlikdao-lib. While we used it on our code for a while now, it has not been fuzzed on any test suites yet. The fast mode should work on virtually on any valid TypeScript, however the opt mode very likely doesn't support large parts of TypeScript and even some parts of JavaScript. While we keep adding missing pieces and improving kdts actively, some parts of TypeScript will likely be never supported. kdts is not a drop-in replacement for tsc and being so is a non-goal.

In opt mode, each npm package used in the program should export its own types that kdts is able to parse, or you need to provide declaration shims by creating a directory @types/ in the working directory or by adding to kdts/@types. We currently have declaration shims for a very limited set of npm packages that we use; see Contributing.

kdts is under active development, and implementation coverage does not yet match this document in every case, particularly for opt mode. When in doubt, check our library code at kimlikdao-lib which is built and tested in kdts opt mode with the --strict flag. Every feature of kdts is used somewhere in kimlikdao-lib.

For a showcase of examples, see showcase. For a real library built using kdts opt mode, see kimlikdao-lib.

Contributing

Feel free to file issues, send PRs, add declaration shims at https://github.com/KimlikDAO/kdts.