API reference / @evolu/common / Brand / Brand
Interface: Brand<B>
Defined in: packages/common/src/Brand.ts:59
A utility interface for creating branded types.
Branded types enhance type safety by differentiating otherwise identical base
types, such as number or string, to enforce stricter type checks.
Supports multiple brands, allowing types to act like flags.
Example 1: Single Brand
// A branded type definition
type UserId = number & Brand<"UserId">;
// A function that creates `UserId` values.
// Casting with `as UserId` is unsafe, so `createUserId` must be unit-tested.
const createUserId = (): UserId => {
return 123 as UserId; // Unsafe casting
};
const userId = createUserId();
// A function that accepts only `UserId`.
const getUser = (id: UserId) => {
// Implementation
};
getUser(userId); // ✅ Valid
getUser(123); // ❌ TypeScript error
getUser("123"); // ❌ TypeScript error
Example 2: Multiple Brands
// Define branded types
type Min1 = string & Brand<"Min1">;
type Max100 = string & Brand<"Max100">;
type Min1Max100 = string & Brand<"Min1" | "Max100">;
// Functions requiring specific brands
const requiresMin1 = (value: Min1): void => {};
const requiresMax100 = (value: Max100): void => {};
// Values with single brands
const min1Value: Min1 = "hello" as Min1;
const max100Value: Max100 = "world" as Max100;
// Value with multiple brands
const min1Max100Value: Min1Max100 = "typescript" as Min1Max100;
// Valid cases
requiresMin1(min1Value); // ✅ Valid
requiresMax100(max100Value); // ✅ Valid
requiresMin1(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Min1
requiresMax100(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Max100
Extended by
Type Parameters
| Type Parameter |
|---|
B extends string |
Properties
| Property | Modifier | Type | Defined in |
|---|---|---|---|
[___brand] | readonly | Readonly<Record<B, true>> | packages/common/src/Brand.ts:60 |