Брендовані типи (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+ підтримує пайп у кастомний бренд:
  .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);
}