Sepse TypeScript është tipizuar strukturalisht, një UserId dhe një OrderId që janë të dyja string janë të këmbyeshme — përpiluesi nuk mund të të ndalojë nga përzierja e tyre. Llojet me shënim simulojnë tipizimin duke bashkangjitur një "shënim" unik dhe fantazëm, në mënyrë që llojet në të tjera identike të bëhen të ndryshme.
// the brand is a property that exists only in the type system, never at runtime
type Brand<T, B> = T & { readonly __brand: B };
type UserId = Brand<string, "UserId">;
type OrderId = Brand<string, "OrderId">;
function getUser(id: UserId) { return id; }
const uid = "u1" as UserId;
const oid = "o1" as OrderId;
getUser(uid); // ✅
getUser(oid); // ❌ Error: OrderId is not assignable to UserId
getUser("u1"); // ❌ Error: plain string is not a UserId
Proprieteti __brand nuk ekziston kurrë në kohën e ekzekutimit (vlera është thjesht një varg), por në sistemin e tipeve e bën UserId dhe OrderId të papajtueshëm — duke parandaluar një klasë të tërë gabimesh të ngatërrimit.
function toUserId(s: string): UserId {
if (!s.startsWith("u")) throw new Error("invalid UserId");
return s as UserId; // validation happens here, once
}
Vazhdo një herë në kufirin; pjesa e mbetur e kodit i beson llojit me shënim.
ID-et (UserId vs OrderId), vargjet e validuar/të pastruar (Email, SafeHtml), njësi (Meters vs Feet), PositiveNumber — kudo ku dy vlera ndajnë një lloj primitiv, por nuk duhet të ngatërrohen.
Llojet me shënim shtojnë siguri nominale ku tipizimi struktural është shumë përleborues.
Ato kapine përzimet e rendit të argumentit dhe ngatërrimet "pa validim versus i validuar" në kohën e përpilimit, pa asnjë kosto në kohën e ekzekutimit — një model i fuqishëm për modelimin e domenit në baza kodi të mëdha, kritike për korrektësinë.