Брендированные типы (Branded Types) и номинальная типизация

// Ошибка, которую компилятор со структурной типизацией НЕ способен обнаружить:
function transferFunds(senderId: string, recipientId: string, amountCents: number) {}

const currentUserId = 'usr_1024';
const targetOrderId = 'ord_9876';

// Баг: передача OrderId вместо RecipientId проходит компиляцию без предупреждений!
transferFunds(currentUserId, targetOrderId, 5000);

+-------------------------------------------------------------------------+
|                  СТРУКТУРНАЯ VS НОМИНАЛЬНАЯ ТИПИЗАЦИЯ                   |
+-------------------------------------------------------------------------+
| [Структурная типизация: Примитивы эквивалентны]                         |
| type UserId = string;                                                   |
| type OrderId = string;                                                  |
| string === string -> Полная взаимозаменяемость (Опасно для домена!)     |
+-------------------------------------------------------------------------+
                                    |
                                    v
+-------------------------------------------------------------------------+
| [Брендированные типы: Изолированные доменные сущности]                 |
| type UserId = string & { readonly [__brand]: 'UserId' };                |
| type OrderId = string & { readonly [__brand]: 'OrderId' };              |
| Компилятор:                                                             |
| Type '{ [__brand]: "OrderId" }' is not assignable to '{ [__brand]: "UserId" }'|
+-------------------------------------------------------------------------+

Жизненный цикл брендированного типа:
[Сырая строка из HTTP/БД: string]
               |
               v
  [Smart Constructor / Zod-схема]
  Проверка: regex.test(raw), uuid.validate(raw)
         /               \
     (Успех)           (Ошибка)
       /                   \
      v                     v
[UserId (Brand)]     [DomainError / Throw]
      |
      v
[Доменные сервисы принимают ТОЛЬКО валидированный UserId]

declare const __brand: unique symbol;

/**
 * Базовый вспомогательный тип для создания жестких брендов (Nominal Types).
 */
export type Brand<T, TBrand extends string | symbol> = T & {
  readonly [__brand]: TBrand;
};

/**
 * Альтернатива: Мягкий бренд (Flavoring).
 * Позволяет неявно передавать базовый примитив в операции чтения, но требует бренд для записи.
 */
declare const __flavor: unique symbol;
export type Flavor<T, TFlavor extends string | symbol> = T & {
  readonly [__flavor]?: TFlavor;
};

import { Brand } from '../types/brand';

// Декларация брендированных типов
export type UserId = Brand<string, 'UserId'>;
export type AccountId = Brand<string, 'AccountId'>;
export type UsdCents = Brand<number, 'UsdCents'>;

// Smart Constructor для идентификатора пользователя с валидацией UUIDv4
export function parseUserId(raw: string): UserId {
  const uuidRegex =
    /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

  if (!uuidRegex.test(raw)) {
    throw new TypeError(`[DomainError] Невалидный формат UserId: ${raw}`);
  }

  // Единственное место принудительного каста — внутри валидирующей фабрики
  return raw as UserId;
}

// Smart Constructor для денежных величин с валидацией целочисленности и неотрицательности
export function createUsdCents(amount: number): UsdCents {
  if (!Number.isSafeInteger(amount) || amount < 0) {
    throw new RangeError(
      `[DomainError] Сумма в центах обязана быть неотрицательным целым числом. Получено: ${amount}`
    );
  }

  return amount as UsdCents;
}

// Доменный сервис с абсолютной защитой от перестановки аргументов
export function processTransfer(
  fromAccount: AccountId,
  toAccount: AccountId,
  amount: UsdCents,
  authorizedBy: UserId
): void {
  // Реализация бизнес-логики перевода
  console.log(
    `Перевод ${amount} центов со счета ${fromAccount} на счет ${toAccount} (авторизовал: ${authorizedBy})`
  );
}

import { z } from 'zod';
import { Brand } from '../types/brand';

export type UserEmail = Brand<string, 'UserEmail'>;

export const UserEmailSchema = z
  .string()
  .email('Некорректный синтаксис email адреса')
  .transform((val) => val.toLowerCase().trim())
  .refine((val) => val.length <= 255, 'Email превышает максимальную длину 255 символов')
  // Zod v3+ поддерживает нативное брендирование, либо кастомный brand:
  .pipe(z.custom<UserEmail>());

export interface RegisterUserDto {
  readonly email: UserEmail;
  readonly fullName: string;
}

export function parseRegisterUserPayload(input: unknown): RegisterUserDto {
  const Schema = z.object({
    email: UserEmailSchema,
    fullName: z.string().min(2),
  });

  return Schema.parse(input);
}