¿Cómo evito que un `UserId` se pase donde se esperaba un `OrderId`, si ambos son solo cadenas?

La receta

declare const brand: unique symbol

type Brand<T, Name extends string> = T & { readonly [brand]: Name }

type UserId = Brand<string, 'UserId'>
type OrderId = Brand<string, 'OrderId'>

const asUserId = (raw: string): UserId => raw as UserId

declare function findUser(id: UserId): void

const id = asUserId('u_1')
findUser(id)

La compilación compila esto y comprueba cada resultado de abajo.

Cómo funciona

1. 01

   declare const brand: unique symbol

   Un `unique symbol` da una clave que nada más puede producir. Una clave de cadena permitiría que un objeto ajeno satisficiera la marca por accidente.

2. 02

   type Brand<T, Name extends string> = T & { readonly [brand]: Name }

   La intersección añade una propiedad que solo existe en el tipo. En tiempo de ejecución el valor sigue siendo exactamente la cadena de partida.

3. 03

   const asUserId = (raw: string): UserId => raw as UserId

   Un cast, en un solo sitio, es el precio. En todo lo demás el compilador impone la distinción gratis — por eso esta función debería ser la única entrada.

Lo que obtienes

• UserId extends string ? true : false

  →true

• string extends UserId ? true : false

  →false

  La asimetría es toda la característica: un id marcado sigue siendo una cadena, pero una cadena a secas no es un id marcado.

• UserId extends OrderId ? true : false

  →false

Dónde falla

La marca se borra, así que `JSON.parse` te dará sin problema algo tipado como `UserId` que nunca pasó por tu constructor. Las marcas protegen tu código de sí mismo; no validan datos que cruzan una frontera.