# kdts

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**

```shellscript
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 `class`es and `interface`s are nominal types whereas object types are structural; see [Types and declarations](/types-and-declarations.md#nominal-and-structural-types).

#### **Usage**

Compile any program with

```shellscript
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

```shellscript
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,

```shellscript
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](https://github.com/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](https://github.com/KimlikDAO/kdts/tree/main/kdts/%40types). We currently have declaration shims for a very limited set of npm packages that we use; see [#contributing](#contributing "mention").

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](https://github.com/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](https://github.com/KimlikDAO/lib).

For a showcase of examples, see [showcase](https://github.com/KimlikDAO/kdts/tree/main/showcase). For a real library built using kdts opt mode, see [kimlikdao-lib](https://github.com/KimlikDAO/lib).

#### **Contributing**

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kimlikdao.org/introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.