Tipos con marca (Branded Types) y tipado nominal

// Error que un compilador con tipado estructural NO puede detectar:
function transferFunds(senderId: string, recipientId: string, amountCents: number) {}

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

// Bug: ¡pasar OrderId en vez de RecipientId compila sin advertencias!
transferFunds(currentUserId, targetOrderId, 5000);

+-------------------------------------------------------------------------+
|                  TIPADO ESTRUCTURAL VS TIPADO NOMINAL                   |
+-------------------------------------------------------------------------+
| [Tipado estructural: Los primitivos son equivalentes]                   |
| type UserId = string;                                                   |
| type OrderId = string;                                                  |
| string === string -> Total intercambiabilidad (¡Peligroso en dominio!)  |
+-------------------------------------------------------------------------+
                                    |
                                    v
+-------------------------------------------------------------------------+
| [Tipos con marca: Entidades de dominio aisladas]                        |
| type UserId = string & { readonly [__brand]: 'UserId' };                |
| type OrderId = string & { readonly [__brand]: 'OrderId' };              |
| Compilador:                                                             |
| Type '{ [__brand]: "OrderId" }' is not assignable to '{ [__brand]: "UserId" }'|
+-------------------------------------------------------------------------+

Ciclo de vida de un tipo con marca:
[Cadena no confiable de HTTP/BD: string]
               |
               v
   [Smart Constructor / Esquema Zod]
   Validación: regex.test(raw), uuid.validate(raw)
          /               \
      (Éxito)          (Fallo)
        /                   \
       v                     v
 [UserId (Brand)]     [DomainError / Throw]
       |
       v
[Los servicios de dominio aceptan ÚNICAMENTE UserId validado]

declare const __brand: unique symbol;

/**
 * Tipo utilitario base para generar marcas estrictas (Tipos nominales).
 */
export type Brand<T, TBrand extends string | symbol> = T & {
  readonly [__brand]: TBrand;
};

/**
 * Alternativa: Marcado suave (Flavoring).
 * Permite asignar implícitamente el primitivo base en lectura, pero exige la marca en escritura.
 */
declare const __flavor: unique symbol;
export type Flavor<T, TFlavor extends string | symbol> = T & {
  readonly [__flavor]?: TFlavor;
};

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

// Declaración de tipos con marca
export type UserId = Brand<string, 'UserId'>;
export type AccountId = Brand<string, 'AccountId'>;
export type UsdCents = Brand<number, 'UsdCents'>;

// Smart Constructor para UserId con validación de 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] Formato de UserId no válido: ${raw}`);
  }

  // Único lugar donde se permite la aserción de tipo: dentro de la fábrica validadora
  return raw as UserId;
}

// Smart Constructor para importes monetarios que valida enteros no negativos
export function createUsdCents(amount: number): UsdCents {
  if (!Number.isSafeInteger(amount) || amount < 0) {
    throw new RangeError(
      `[DomainError] El importe en centavos debe ser un entero no negativo. Recibido: ${amount}`
    );
  }

  return amount as UsdCents;
}

// Servicio de dominio con protección contra la transposición de parámetros
export function processTransfer(
  fromAccount: AccountId,
  toAccount: AccountId,
  amount: UsdCents,
  authorizedBy: UserId
): void {
  // Lógica de negocio de la transferencia
  console.log(
    `Transferencia de ${amount} centavos de ${fromAccount} a ${toAccount} (autorizado por: ${authorizedBy})`
  );
}

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

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

export const UserEmailSchema = z
  .string()
  .email('Sintaxis de correo electrónico no válida')
  .transform((val) => val.toLowerCase().trim())
  .refine((val) => val.length <= 255, 'El correo supera la longitud máxima de 255 caracteres')
  // Canalización al tipo con marca personalizado:
  .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);
}