Branded Type TypeScript: Nominal Typing dengan Contoh

TypeScript membandingkan tipe berdasarkan bentuknya, jadi dua alias dari string bisa saling menggantikan. Branded type menambahkan tag yang hanya ada di sistem tipe, string & { readonly __brand: "UserId" }, yang membuat UserId tidak kompatibel dengan string biasa maupun dengan brand lainnya:

type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function loadUser(id: UserId) {
  console.log("loading user", id);
}

const userId = "u_42" as UserId;
const orderId = "ord_7" as OrderId;

loadUser(userId); // loading user u_42

// @ts-expect-error: an OrderId is not a UserId
loadUser(orderId); // loading user ord_7 (the error is suppressed, and types do not exist at runtime)

Saat runtime, userId hanyalah string "u_42". Brand adalah label saat kompilasi, dan satu-satunya tugasnya adalah mencegah ID, satuan, dan string yang sudah divalidasi tertukar.

Masalahnya: Alias Hanya Sebuah Nama

Type alias tidak membuat tipe baru. Alias memberikan nama kedua untuk tipe yang sudah ada, dan compiler memperlakukan kedua nama itu sebagai hal yang sama:

type UserId = string;
type OrderId = string;

function cancelOrder(id: OrderId) {
  console.log("cancelling", id);
}

const user: UserId = "u_42";
cancelOrder(user); // compiles: both are just string
// cancelling u_42  (the bug ships)

Ini adalah structural typing: TypeScript memeriksa apakah bentuknya cocok, dan string cocok dengan string. Untuk objek, bentuknya biasanya berbeda; untuk ID, email, mata uang, dan satuan, bentuknya tidak pernah berbeda. Brand memperbaiki kasus yang satu itu.

Cara Kerja Brand

string & { readonly __brand: "UserId" } adalah intersection: sebuah nilai harus berupa string dan juga punya property __brand bertipe "UserId". Tidak ada string sungguhan yang punya property itu, jadi tidak ada string biasa yang bisa diberikan kepadanya:

// This does not compile: a plain string, and a different brand, are both rejected
type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function loadUser(id: UserId) {
  console.log("loading user", id);
}

const orderId = "ord_7" as OrderId;
loadUser("u_42");
loadUser(orderId);

index.ts(10,10): error TS2345: Argument of type 'string' is not assignable to parameter of type 'UserId'.
  Type 'string' is not assignable to type '{ readonly __brand: "UserId"; }'.
index.ts(11,10): error TS2345: Argument of type 'OrderId' is not assignable to parameter of type 'UserId'.
  Type 'OrderId' is not assignable to type '{ readonly __brand: "UserId"; }'.
    Types of property '__brand' are incompatible.
      Type '"OrderId"' is not assignable to type '"UserId"'.

Arah yang penting tetap berjalan: UserId adalah string, jadi kamu bisa mengirimnya ke apa pun yang menerima string, memanggil .startsWith() padanya, atau memasukkannya ke template. Brand hanya menghalangi jalan masuknya.

Fungsi Constructor yang Memvalidasi

Assertion as UserId adalah satu-satunya jalan masuk, dan assertion tidak memeriksa apa pun. Taruh di satu fungsi yang memvalidasi input-nya, maka setiap nilai ber-brand di program dipastikan sudah lolos pemeriksaan itu:

type Email = string & { readonly __brand: "Email" };

function toEmail(input: string): Email {
  const trimmed = input.trim().toLowerCase();
  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(trimmed)) {
    throw new Error(`not an email: ${input}`);
  }
  return trimmed as Email; // the only "as Email" in the codebase
}

function sendWelcome(to: Email) {
  console.log("sending to", to);
}

sendWelcome(toEmail("  Ada@Example.com ")); // sending to ada@example.com

try {
  sendWelcome(toEmail("ada at example"));
} catch (e) {
  console.log((e as Error).message); // not an email: ada at example
}

sendWelcome tidak pernah memeriksa input-nya lagi, karena tipe parameternya menyatakan pemeriksaan sudah dilakukan. Inilah ide "parse, don't validate": periksa di batas, lalu bawa buktinya di dalam tipe. Type guard juga bisa berfungsi sebagai constructor kalau kamu lebih suka boolean daripada exception: function isEmail(s: string): s is Email.

Helper Brand Generic

Menulis intersection secara manual untuk setiap tipe jadi berulang-ulang. Satu generic kecil cukup melakukannya sekali:

type Brand<T, Name extends string> = T & { readonly __brand: Name };

type ProductId = Brand<string, "ProductId">;
type Cents = Brand<number, "Cents">;

const cents = (n: number): Cents => {
  if (!Number.isInteger(n)) throw new Error("cents must be whole");
  return n as Cents;
};

function price(id: ProductId, amount: Cents): string {
  return `${id}: $${(amount / 100).toFixed(2)}`;
}

console.log(price("p_1" as ProductId, cents(1999))); // p_1: $19.99

Memberi brand pada number sama caranya dengan memberi brand pada string. Perhatikan bahwa amount / 100 adalah number biasa: aritmetika pada number ber-brand menghasilkan nilai tanpa brand, seperti dibahas di bawah.

Brand dengan unique symbol

Nama property berupa string seperti __brand terlihat seperti property sungguhan: userId.__brand lolos pemeriksaan tipe sebagai "UserId" tetapi bernilai undefined saat runtime, dan dua library bisa saja memilih nama yang sama. Key berupa unique symbol menghindari keduanya:

declare const brand: unique symbol;

type Brand<T, Name extends string> = T & { readonly [brand]: Name };

type Meters = Brand<number, "Meters">;
type Feet = Brand<number, "Feet">;

function toMeters(feet: Feet): Meters {
  return (feet * 0.3048) as Meters;
}

const height = 10 as Feet;
const inMeters = toMeters(height);
console.log(inMeters.toFixed(3)); // 3.048

// @ts-expect-error: Meters is not Feet
toMeters(inMeters);

declare const brand: unique symbol mendeklarasikan symbol yang hanya ada untuk pemeriksa tipe; kata kunci declare berarti tidak ada JavaScript yang dihasilkan untuknya. Karena symbol itu tidak di-export dari modulnya, kode di file lain bahkan tidak bisa menyebut nama property brand-nya, jadi di luar modul itu satu-satunya cara mendapatkan Meters adalah lewat fungsi yang kamu export atau assertion as Meters.

Brand Tidak Punya Biaya Runtime

Output hasil kompilasi tidak menyisakan jejak brand sama sekali. Berikut baris-baris yang dihasilkan untuk contoh Meters, di bawah header modul yang ditambahkan compiler: declare, kedua type alias, dan setiap as sudah hilang, sementara panggilan yang error-nya disembunyikan di baris terakhir tetap dijalankan.

function toMeters(feet) {
    return (feet * 0.3048);
}
const height = 10;
const inMeters = toMeters(height);
console.log(inMeters.toFixed(3)); // 3.048
// @ts-expect-error: Meters is not Feet
toMeters(inMeters);

Nilai ber-brand adalah primitif biasa: typeof menghasilkan "string" atau "number", JSON.stringify menuliskannya seperti biasa, dan perbandingan berjalan seperti sebelumnya. Sisi lainnya, tidak ada yang diperiksa saat runtime kecuali fungsi constructor-mu memeriksanya. Data hasil parse dari JSON, database, atau URL datang sebagai string, dan baru menjadi UserId setelah kamu melewatkannya ke fungsi tersebut.

Aritmetika dan Method Menghilangkan Brand

Operasi pada nilai ber-brand mengembalikan tipe dasarnya, karena brand bukan bagian dari hasil + atau .slice():

type Cents = number & { readonly __brand: "Cents" };

const a = 500 as Cents;
const b = 250 as Cents;

const sum = a + b;           // number, not Cents
const total: Cents = a + b;  // error TS2322: Type 'number' is not assignable to type 'Cents'
const fixed = (a + b) as Cents; // re-brand when the result is still valid

Biasanya itulah yang kamu inginkan: menjumlahkan dua nominal dalam sen menghasilkan sen, tetapi mengalikan sen dengan sen tidak, dan hanya kamu yang tahu operasi mana yang mempertahankan maknanya. Tulis helper kecil seperti addCents(a: Cents, b: Cents): Cents untuk operasi yang dibutuhkan kodemu.

Kapan Memakai Branded Type

Pakai brand ketika tertukarnya dua nilai dengan tipe primitif yang sama adalah risiko nyata dan compiler tidak bisa membantu dengan cara lain:

Lewati brand untuk nilai yang tidak pernah tertukar, dan untuk object type yang bentuknya sudah berbeda. Library validasi bisa menghasilkan branded type dari skema: di Zod, z.string().brand<"UserId">() menghasilkan skema yang parse-nya mengembalikan UserId ber-brand, sehingga kamu tidak perlu menulis fungsi constructor secara manual.