Features That Disappear at Build Time

These transformations all happen at build time. You don’t write any of it — it’s just useful to know what’s going on under the hood.

Phantom ownership types

Owned<T>, Shared<T>, and Mutable<T> are phantom types that exist only in the TypeScript type system for build-time validation. They evaporate completely in the C++ output:

Owned<T> — single ownership

The value is emitted as-is with no wrapper. The transpiler tracks ownership transfers (moves) and reports use-after-move errors.

let buf: Owned<Buffer> = new Buffer(64);
let other = buf;        // ownership transferred (move)
// buf is now invalid — use-after-move diagnostic

C++ output:

Buffer buf(64);
auto other = buf;
// No wrapper types, no reference counting
// The transpiler tracks ownership at compile time only

Shared<T> — immutable borrow

Adds const in C++ for compiler-enforced immutability. The transpiler prevents assignment to Shared variables.

const ref: Shared<Buffer> = buf;
// ref.write() → C++ const method (compiler enforces read-only)

C++ output:

const Buffer& ref = buf;

Mutable<T> — mutable borrow

Emitted as a regular reference. The transpiler enforces exclusivity — no other borrows can exist while a Mutable is active.

const mut: Mutable<Buffer> = buf;
mut.write(data);  // Allowed — mutable borrow

C++ output:

Buffer& mut = buf;

No runtime cost

• No wrapper classes
• No reference counting
• No garbage collection
• Shared<T> adds only a const qualifier — the C++ compiler enforces immutability
• All tracking happens at build time through the ownership validator

Pin handle erasure

TypeScript pin objects become direct function calls or register writes in the C++ output. The HAL class layer does not exist at runtime:

// TypeScript — typed, safe
import { GPIO } from '@typecad/hal';
import { LED } from '@typecad/board';
const led = new GPIO(LED, GPIO.OUTPUT);
led.toggle();

// C++ — no HAL class, no indirection
gpio_pin_configure_dt(&__tc_dt_led, GPIO_OUTPUT);
gpio_pin_toggle_dt(&__tc_dt_led);

The pin’s devicetree spec is resolved from the board definition at build time; the call is the Zephyr driver function with the spec inlined. The flags token (GPIO.OUTPUT ↔ GPIO_OUTPUT) is a TypeScript-only name mapping — no conversion code is generated.

Enum narrowing

The transpiler knows the full, closed value range of every enum at emit time — something the C++ compiler cannot recover. It picks the narrowest underlying type that fits:

enum State { Off, On, Blinking }  // values 0–2

// C++ — narrowed from the default int to the smallest type that fits
enum class State : uint8_t { Off, On, Blinking };

Non-negative ranges that fit in a byte narrow to uint8_t; ranges within [-128, 127] narrow to int8_t. The narrowest-type pick is made once at emit time and stamped into the enum definition — no runtime conversion anywhere.

let → const promotion

The transpiler performs whole-program reassignment analysis — it tracks every assignment to every let binding across all functions and scopes. When it proves a let is never written after initialization, it emits const in C++ automatically:

let threshold = 500;  // never reassigned anywhere in the program

// C++ — promoted to const, enabling ROM placement and constant folding
const int threshold = 500;

This is information the C++ compiler cannot recover across translation units. The inverse demotion (const → non-const when a member is mutated) also applies automatically.

Automatic volatile inference

The classic embedded bug — a global written in an ISR and read in loop() becomes an infinite loop under -Os because the compiler caches it in a register. The transpiler knows which callbacks are interrupt handlers and which globals they write, so it marks shared variables volatile without any user annotation:

let flag = false;
function setup() {
  button.onInterrupt(GPIO.INT_EDGE_FALLING, () => { flag = true; });
}
function loop() {
  if (flag) { flag = false; }
}

// C++ — flag auto-marked volatile
volatile bool flag = false;

The volatile keyword is emitted automatically. This eliminates an entire bug class that the C++ compiler cannot detect — “this function runs in interrupt context” is a call-graph property the transpiler sees but g++ does not.

Tree-shaking (removing unused code)

The transpiler performs dead-code elimination by default. Unused enums, classes, type aliases, and variables are removed from the C++ output.

Tree-shaking flags

How it works

1. The transpiler builds a call graph from the internal representation.
2. It identifies entry points (main() and any functions it calls).
3. Symbols not reachable from any entry point are marked for removal.
4. The C++ emitter skips removed symbols entirely.

Entry point detection is controlled by the platform strategy — main() is always the entry point.

Free-function prototypes

When top-level code calls helper functions defined later in the file, the transpiler automatically inserts forward declarations before main():

// TypeScript — definition after usage
import { Time } from '@typecad/hal';

led.toggle();
Time.sleep(500);

function blink() {
  led.toggle();
}

// C++ — forward declaration inserted
void blink();  // Auto-generated forward declaration

int main() {
  gpio_pin_toggle_dt(&__tc_dt_led);
  k_msleep(500);
  blink();
}

void blink() {
  gpio_pin_toggle_dt(&__tc_dt_led);
}

Default arguments go on the forward declaration, not the definition, so they’re available throughout the file.