Branded Newtypes

Single-field tuple structs (newtypes) become type aliases by default. Enable branded_newtypes for nominal type safety — preventing accidental mixing of structurally identical types like UserId and OrderId.

rust

pub struct UserId(pub String);
pub struct OrderId(pub String);
pub struct Pair(pub String, pub i32);

// Default: plain type aliases
type UserId = string;
type OrderId = string;
type Pair = [string, number];

// Problem: UserId and OrderId are interchangeable
const userId: UserId = "u-123";
const orderId: OrderId = userId; // no error!

// With branded_newtypes = true
type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };
type Pair = [string, number]; // tuples unchanged

// Now they're distinct at compile time
const userId: UserId = "u-123" as UserId;
const orderId: OrderId = userId; // TS error!

toml

# metaxy.config.toml
[codegen]
branded_newtypes = true

or via CLI

metaxy generate --branded-newtypes