How bun compile uses your types

What your TypeScript types do in a compiled program, and how to write code that compiles well

Ahead-of-time compilation is experimental.

bun compile reads your TypeScript types and generates machine code that relies on them. It's still ordinary TypeScript. A type error stops the build. At run time a type never throws and never converts a value. A value that doesn't match its type gives the same result as under bun run, only slower.

What types get you#

account.ts
class Account {
  balance = 0;
}

function total(accounts: Account[]): number {
  let sum = 0;
  for (const account of accounts) sum += account.balance;
  return sum;
}

Every Account has the same fields in the same places, like a struct in Go or Rust, so account.balance is one load from a fixed offset. A call to total is a direct call that the compiler can inline.

You don't have to annotate everything. The compiler follows each object from where it's created to where it's used, in .js files too. Annotations matter where it can't do that, such as the result of JSON.parse or the arguments of a route handler. Without them, that code looks properties up at run time, which is slower.

When a value doesn't match its type#

visits.ts
function double(n: number): number {
  return n * 2;
}

const body: any = JSON.parse('{"visits":"3"}');
console.log(double(body.visits));
terminal
bun compile ./visits.ts && ./visits
6

bun run prints 6 too. TypeScript lets you call a value a number when it isn't one, through any, as, !, JSON.parse and .d.ts files. So where compiled code relies on a declared type, it checks the value first. That check is called a guard. Here the guard sees a string, and the call takes a slower version of double that behaves like plain JavaScript. Nothing throws, and the string stays a string.

Write code that compiles well#

bun compile --explain finds the slow spots in your program. These are the common ones.

Convert, don't cast#

const query: any = { page: "2" };
const page = query.page as number; 
const page = Number(query.page); 
console.log(page + 1);

as, any and ! do nothing at run time. With the cast, page is still a string and this prints 21, compiled or not. With the conversion, the compiler knows that page is a number, so there's no guard to fail.

Build your own objects from what you parse#

const user: User = JSON.parse(text); 
const { id, name } = JSON.parse(text); 
const user: User = { id, name }; 

JSON.parse, response.json() and request.json() return ordinary objects, whatever type you declare for the result. They don't have the fixed layout of User, so every read looks the property up. An object that your own code creates has the layout.

Keep computed keys in a Map#

class Counter {
  count = 0;
  labels = new Map<string, string>(); 
}
(counter as any)[key] = "visits"; 
counter.labels.set(key, "visits"); 

A store with a computed key can change the object's shape. So can Object.defineProperty and Object.setPrototypeOf. Any Counter could be the one that changed, so every access to a Counter gets slower.

32-bit integers#

To TypeScript, and under bun run, int32 is a number. In an executable it takes four bytes instead of eight, and arithmetic on it skips the checks for fractions. It pays off in the fields of objects that you create by the million.

cursor.ts
import type { int32 } from "bun";

class Cursor {
  column: int32 = 0;

  advance(by: int32) {
    this.column = this.column + by; 
    this.column = (this.column + by) | 0; 
  }
}

The build has to prove that every value you store in an int32 is a whole number in range. Where it can't, it stops (TS100031), and the error says what to write. That's usually | 0.

int32 only counts as the whole type of a variable, field, parameter or return value. Inside int32[] or Map<string, int32> it's a number.