TypeScript Branded Types: Örneklerle Nominal Tipleme

TypeScript tipleri şekillerine göre karşılaştırır, bu yüzden string tipinin iki alias'ı birbirinin yerine kullanılabilir. Branded type yalnızca tip sisteminde var olan bir etiket ekler, string & { readonly __brand: "UserId" }. Bu etiket bir UserId değerini düz bir string ile ve diğer her brand ile uyumsuz yapar:

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)

Çalışma zamanında userId sadece "u_42" string'idir. Brand derleme zamanına ait bir etikettir ve tek görevi ID'lerin, birimlerin ve doğrulanmış string'lerin birbirine karışmasını önlemektir.

Sorun: Alias'lar Yalnızca Addır

Bir type alias yeni bir tip oluşturmaz. Var olan bir tipe ikinci bir ad verir ve derleyici iki adı da aynı şey olarak görür:

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)

Buna yapısal tipleme denir: TypeScript şeklin uyup uymadığını kontrol eder ve string, string tipine uyar. Nesnelerde şekiller genellikle farklıdır; ID'lerde, e-postalarda, para birimlerinde ve birimlerde ise hiçbir zaman farklı değildir. Brand'ler bu tek durumu çözer.

Brand Nasıl Çalışır

string & { readonly __brand: "UserId" } bir intersection'dır: değer hem bir string olmalı hem de "UserId" tipinde bir __brand özelliğine sahip olmalıdır. Gerçek hiçbir string'in bu özelliği yoktur, bu yüzden hiçbir düz string bu tipe atanamaz:

// 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"'.

Önemli olan yön yine çalışır: bir UserId bir string'dir, bu yüzden onu string alan her şeye geçirebilir, üzerinde .startsWith() çağırabilir ya da bir template içine koyabilirsiniz. Brand yalnızca giriş yolunu kapatır.

Doğrulama Yapan Constructor Fonksiyonları

as UserId assertion'ı tek giriş yoludur ve bir assertion hiçbir şeyi kontrol etmez. Onu girdiyi doğrulayan tek bir fonksiyona koyun; böylece programdaki her branded değerin bu kontrolden geçtiği bilinir:

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 girdisini bir daha kontrol etmez, çünkü parametre tipi kontrolün zaten yapıldığını söyler. Bu "parse, don't validate" fikridir: sınırda kontrol edin, sonra kanıtı tipte taşıyın. Exception yerine boolean tercih ediyorsanız bir type guard da constructor olarak çalışır: function isEmail(s: string): s is Email.

Generic Bir Brand Yardımcısı

Her tip için intersection'ı elle yazmak tekrara dönüşür. Küçük bir generic bunu bir kez yapar:

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

Bir number'a brand vermek, bir string'e brand vermekle aynı şekilde çalışır. amount / 100 ifadesinin düz bir number olduğuna dikkat edin: branded bir number üzerindeki aritmetik brand'siz bir sonuç verir, bu konu aşağıda ele alınıyor.

unique symbol Brand'leri

__brand gibi string bir özellik adı gerçek bir özellik gibi görünür: userId.__brand tip kontrolünde "UserId" olarak geçer ama çalışma zamanında undefined olur ve iki kütüphane aynı adı seçebilir. Bir unique symbol anahtarı ikisini de önler:

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, yalnızca tip denetleyicisi için var olan bir symbol bildirir; declare anahtar kelimesi onun için hiç JavaScript üretilmeyeceği anlamına gelir. Symbol kendi modülünden export edilmediği için diğer dosyalardaki kod brand özelliğini adlandıramaz bile; bu yüzden o modülün dışında bir Meters elde etmenin tek yolları export ettiğiniz fonksiyonlar ya da bir as Meters assertion'ıdır.

Brand'lerin Çalışma Zamanında Maliyeti Yoktur

Derlenen çıktıda brand'den hiçbir iz kalmaz. Meters örneği için, derleyicinin eklediği modül başlığının altında üretilen satırlar bunlardır: declare, iki type alias ve her as kaybolmuştur, son satırdaki bastırılmış çağrı ise yine çalışır.

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);

Branded bir değer düz primitive'in kendisidir: typeof "string" ya da "number" verir, JSON.stringify onu her zamanki gibi yazar ve karşılaştırmalar önceki gibi çalışır. Öte yandan constructor fonksiyonunuz kontrol etmedikçe çalışma zamanında hiçbir şey kontrol edilmez. JSON'dan, bir veritabanından ya da bir URL'den okunan veri string olarak gelir ve ancak o fonksiyondan geçirdiğinizde bir UserId olur.

Aritmetik ve Metotlar Brand'i Düşürür

Branded bir değer üzerindeki işlemler temel tipi döndürür, çünkü brand + ya da .slice() işlemlerinin ürettiği şeyin parçası değildir:

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

Genellikle istediğiniz de budur: cent cinsinden iki tutarı toplamak cent verir, ama cent'i cent ile çarpmak vermez ve hangi işlemlerin anlamı koruduğunu yalnızca siz bilirsiniz. Kodunuzun ihtiyaç duyduğu işlemler için addCents(a: Cents, b: Cents): Cents gibi küçük yardımcılar yazın.

Branded Types Ne Zaman Kullanılır

Aynı primitive tipteki iki değeri karıştırmanın gerçek bir risk olduğu ve derleyicinin başka türlü yardım edemediği yerlerde brand kullanın:

Hiçbir zaman karıştırılmayan değerlerde ve şekli zaten farklı olan nesne tiplerinde bunları kullanmayın. Doğrulama kütüphaneleri bir şemadan branded tipler üretebilir: Zod'da z.string().brand<"UserId">(), parse metodu branded bir UserId döndüren bir şema verir; bu da constructor fonksiyonlarını elle yazma zahmetinden kurtarır.