Typescript Branded Type

branded_types.md

Branded Types

A "Branded" type is a type that is a subtype of the original type, but has a unique literal value in a common field (the brand). This allows us to define types that are more specific than the original type, but are still compatible with it. For example, we have the type EmailAddress, which is a string that is guaranteed to be a valid email address.

Branded types can only be created by calling the brand function, which takes a value of the original type and returns a value of the branded type.

Usage

Creating a new Branded type

Branded types are composed of a union of their original type and a brand object.

EG:

type EmailAddress = string & { __brand: "EmailAddress" };

Branded types should be grouped by their common base type, and should only consist of that type and the brand object.

email.ts

export type EmailAddress = string & {__brand: 'emailAddress'};

/**
 * EmailAddress assertion function
 */
export function assertIsEmailAddress(
  emailAddress: unknown
): asserts emailAddress is EmailAddress {
  if (!isEmailAddress(emailAddress)) {
    throw new Error(`Expected ${emailAddress} to be a valid email address`);
  }
}

/**
 * Email address type check function
 */
export function isEmailAddress(
  emailAddress: unknown
): emailAddress is EmailAddress {
  const emailRegex = /^[\w-.]+@([\w-]+\.)+[\w-]{2,4}$/;
  return typeof emailAddress === 'string' && emailRegex.test(emailAddress);
}

users.ts

interface Credentials {
  login: string;
  password: string;
}

export type UserTypes = 'orgAdmin' | 'superAdmin' | 'standardUser';

export type BrandedCredentials<T extends UserTypes> = Credentials & {
  __brand: T;
};

export type OrgAdmin = BrandedCredentials<'orgAdmin'>;
export type SuperAdmin = BrandedCredentials<'superAdmin'>;
export type StandardUser = BrandedCredentials<'standardUser'>;

export function assertIsOrgAdmin(
  credentials: unknown
): asserts credentials is OrgAdmin {
  if (!isOrgAdmin(credentials)) {
    throw new Error('Not an OrgAdmin');
  }
}

export function assertIsSuperAdmin(
  credentials: unknown
): asserts credentials is SuperAdmin {
  if (!isSuperAdmin(credentials)) {
    throw new Error('Not a SuperAdmin');
  }
}

export function assertIsStandardUser(
  credentials: unknown
): asserts credentials is StandardUser {
  if (!isStandardUser(credentials)) {
    throw new Error('Not a StandardUser');
  }
}

export function isOrgAdmin(credentials: unknown): credentials is OrgAdmin {
  return (credentials as OrgAdmin).__brand === 'orgAdmin';
}

function isSuperAdmin(credentials: unknown): credentials is SuperAdmin {
  return (credentials as SuperAdmin).__brand === 'superAdmin';
}

export function isStandardUser(
  credentials: unknown
): credentials is StandardUser {
  return (credentials as StandardUser).__brand === 'standardUser';
}

uuid.ts

export type UUID = string & {__brand: 'UUID'};

/**
 * Hex string in the format of xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
 */
export const UUIDREGEX =
  /^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$/;

/**
 * UUID assertion function
 * Hex string in the format of xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
 */
export function assertUUID(uuid: string): asserts uuid is UUID {
  if (!isUUID(uuid)) {
    throw new Error(`Expected ${uuid} to be a valid UUID`);
  }
}

/**
 * UUID type check function
 * Hex string in the format of xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
 */
export function isUUID(uuid: string): uuid is UUID {
  return uuid.match(UUIDREGEX) !== null;
}