API Reference / @evolu/common / Types / Brand
Interface: Brand<B>
Defined in: packages/common/src/Types.ts:139
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
Type Parameters
Type Parameter |
---|
B extends string |
Properties
Property | Modifier | Type | Defined in |
---|---|---|---|
[___brand] | readonly | Readonly <Record <B , true >> | packages/common/src/Types.ts:140 |