Discriminated Unions

Q: O que o padrão assertNever faz e por que é útil?

Colocado no caso default de um switch, ele captura casos ausentes em tempo de compilação. Se você adicionar um novo membro à união, mas esquecer de tratá-lo, o TypeScript dará erro porque o novo tipo não é atribuível a never.

Q: Armadilha: Por que desestruturar props antes do switch quebra o estreitamento?

Escrever const { variant } = props; switch (variant) quebra a conexão entre variant e o resto de props. O TypeScript não consegue mais estreitar props para o membro correto da união. Sempre use switch (props.variant) para preservar o estreitamento.

Q: Como modelar estados de carregamento de dados assíncronos com uma união discriminada?

Cada status tem exatamente os campos de que precisa. data só é acessível quando status é "success".

Q: Você pode usar o operador in em vez de um campo discriminante para estreitamento?

Sim. if ("retryAction" in props) estreita para o membro da união que possui retryAction. Isso funciona sem um campo discriminante dedicado. Ele apenas verifica a existência da propriedade, não o tipo do valor.

Q: Como a palavra-chave satisfies funciona com uniões discriminadas?

satisfies valida que um objeto corresponde a uma união sem alargar seu tipo. O tipo inferido preserva os valores literais específicos. Útil para objetos de configuração que devem estar em conformidade com a forma de uma união.

Q: Como você tipa props condicionais sem um campo discriminante?

O TypeScript garante que onDismiss é obrigatório apenas quando dismissible é true. Quando dismissible é false ou omitido, onDismiss não pode ser passado.

Receita

Use tipos de união discriminados para modelar props de componentes que mudam de forma com base em um campo de variante ou status. Obtenha correspondência de padrões exaustiva para que o TypeScript detecte casos ausentes em tempo de compilação.

Exemplo de Trabalho

// Props que mudam de forma com base em um discriminante "variant"
type AlertProps =
  | { variant: "success"; message: string }
  | { variant: "error"; message: string; retryAction: () => void }
  | { variant: "loading" };
 
function Alert(props: AlertProps) {
  switch (props.variant) {
    case "success":
      return <div className="alert-success">{props.message}</div>;
    case "error":
      return (
        <div className="alert-error">
          <p>{props.message}</p>
          <button onClick={props.retryAction}>Tentar Novamente</button>
        </div>
      );
    case "loading":
      return <div className="alert-loading">Carregando...</div>;
  }
}
 
// Uso
<Alert variant="success" message="Salvo!" />
<Alert variant="error" message="Falhou" retryAction={() => refetch()} />
<Alert variant="loading" />

// Helper de verificação exaustiva
function assertNever(value: never): never {
  throw new Error(`Valor inesperado: ${value}`);
}
 
function getStatusColor(props: AlertProps): string {
  switch (props.variant) {
    case "success": return "green";
    case "error": return "red";
    case "loading": return "gray";
    default: return assertNever(props);
    // Se você adicionar uma nova variante e esquecer de tratá-la,
    // o TypeScript dará erro nesta linha.
  }
}

Análise Detalhada

Como Funciona

Uma união discriminada tem um campo literal comum (o "discriminante") que o TypeScript usa para estreitar o tipo. Em AlertProps, o discriminante é variant.
Dentro de um bloco switch ou if que verifica o discriminante, o TypeScript estreita o tipo para o membro específico da união. No caso "error", props.retryAction está disponível porque o TypeScript sabe que props é { variant: "error"; message: string; retryAction: () => void }.
O padrão assertNever captura casos ausentes em tempo de compilação. Se você adicionar uma nova variante à união, mas esquecer de tratá-la no switch, o TypeScript dará erro porque a nova variante de tipo não é atribuível a never.
Uniões discriminadas são mais seguras em termos de tipo do que props opcionais porque tornam estados impossíveis irrepresentáveis. Você não pode passar retryAction para um alerta "success".

Variações

Padrão de dados assíncronos:

type AsyncData<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };
 
function UserProfile({ state }: { state: AsyncData<User> }) {
  switch (state.status) {
    case "idle":
      return null;
    case "loading":
      return <Spinner />;
    case "success":
      return <div>{state.data.name}</div>;
    case "error":
      return <div>Erro: {state.error.message}</div>;
  }
}

União de campo de formulário:

type FormField =
  | { type: "text"; label: string; placeholder?: string }
  | { type: "select"; label: string; options: string[] }
  | { type: "checkbox"; label: string; checked: boolean };
 
function FormFieldComponent({ field }: { field: FormField }) {
  switch (field.type) {
    case "text":
      return <input type="text" placeholder={field.placeholder} />;
    case "select":
      return (
        <select>
          {field.options.map((opt) => <option key={opt}>{opt}</option>)}
        </select>
      );
    case "checkbox":
      return <input type="checkbox" defaultChecked={field.checked} />;
  }
}

Props condicionais sem um discriminante:

type ModalProps =
  | { dismissible: true; onDismiss: () => void }
  | { dismissible?: false };
 
// O TypeScript garante: se dismissible for true, onDismiss é obrigatório

Notas do TypeScript

O campo discriminante deve ser um tipo literal (literal de string, literal de número ou literal booleano). Um campo do tipo string não funciona para estreitamento.
Você pode usar o estreitamento do operador in como alternativa: if ("retryAction" in props) estreita para o membro da união que possui retryAction.
A palavra-chave satisfies pode validar que um objeto corresponde a uma união sem alargar o tipo.

Armadilhas

Desestruturar props antes do switch quebra o estreitamento. Escreva switch (props.variant) em vez de const { variant } = props; switch (variant) -- o último perde a conexão entre variant e o resto de props.
Adicionar um novo membro à união sem atualizar todas as instruções switch é um bug silencioso, a menos que você use o padrão assertNever ou habilite noFallthroughCasesInSwitch.
Uniões discriminadas só estreitam quando o TypeScript pode ver a verificação do discriminante. Extrair a verificação para uma função separada requer um predicado de tipo.
Usar default: return null em vez de assertNever não detectará casos ausentes em tempo de compilação.

Alternativas

Abordagem	Prós	Contras
Uniões discriminadas	Estados impossíveis são irrepresentáveis	Definições de tipo mais verbosas
Props opcionais	Definições de tipo mais simples	Permite combinações de props inválidas
Discriminante de enum	Constantes nomeadas, autocompletar IDE	Enums têm sobrecarga de tempo de execução, uniões de string são preferidas
Componentes polimórficos	Componente único, muitas formas	Assinaturas de tipo complexas
Componentes separados por variante	Cada componente é simples e focado	Duplicação de lógica compartilhada

FAQs

O que é uma união discriminada e qual é o "discriminante"?

Uma união discriminada é um tipo de união onde cada membro tem um campo literal comum (o discriminante).
O TypeScript usa o discriminante para estreitar o tipo dentro de blocos switch ou if.
Exemplo: em { variant: "success" } | { variant: "error" }, o discriminante é variant.

Por que as uniões discriminadas são mais seguras em termos de tipo do que props opcionais?

Elas tornam estados impossíveis irrepresentáveis.
Você não pode passar retryAction para um alerta "success" -- o sistema de tipos impede isso.
Props opcionais permitem qualquer combinação, incluindo inválidas.

O que o padrão `assertNever` faz e por que é útil?

function assertNever(value: never): never {
  throw new Error(`Valor inesperado: ${value}`);
}

Colocado no caso default de um switch, ele captura casos ausentes em tempo de compilação.
Se você adicionar um novo membro à união, mas esquecer de tratá-lo, o TypeScript dará erro porque o novo tipo não é atribuível a never.

O campo discriminante pode ser um número ou booleano, ou deve ser uma string?

O discriminante deve ser um tipo literal: literal de string, literal de número ou literal booleano.
Um tipo string ou number simples não funciona para estreitamento.
Literais de string são a escolha mais comum.

Armadilha: Por que desestruturar props antes do switch quebra o estreitamento?

Escrever const { variant } = props; switch (variant) quebra a conexão entre variant e o resto de props.
O TypeScript não consegue mais estreitar props para o membro correto da união.
Sempre use switch (props.variant) para preservar o estreitamento.

Como modelar estados de carregamento de dados assíncronos com uma união discriminada?

type AsyncData<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };

Cada status tem exatamente os campos de que precisa.
data só é acessível quando status é "success".

Você pode usar o operador `in` em vez de um campo discriminante para estreitamento?

Sim. if ("retryAction" in props) estreita para o membro da união que possui retryAction.
Isso funciona sem um campo discriminante dedicado.
Ele apenas verifica a existência da propriedade, não o tipo do valor.

Armadilha: O que acontece se você usar `default: return null` em vez de `assertNever` em um switch?

O TypeScript não detectará casos ausentes em tempo de compilação.
Novos membros da união adicionados posteriormente passarão silenciosamente para o caso padrão.
Use assertNever para obter verificação de exaustividade em tempo de compilação.

Como a palavra-chave `satisfies` funciona com uniões discriminadas?

satisfies valida que um objeto corresponde a uma união sem alargar seu tipo.
O tipo inferido preserva os valores literais específicos.
Útil para objetos de configuração que devem estar em conformidade com a forma de uma união.

Como você tipa props condicionais sem um campo discriminante?

type ModalProps =
  | { dismissible: true; onDismiss: () => void }
  | { dismissible?: false };

O TypeScript garante que onDismiss é obrigatório apenas quando dismissible é true.
Quando dismissible é false ou omitido, onDismiss não pode ser passado.

Quando você escolheria componentes separados por variante em vez de um único componente de união discriminada?

Componentes separados são mais simples e focados, sem lógica de switch.
Um único componente com uma união discriminada evita duplicar a lógica de renderização compartilhada.
Escolha com base em quanta lógica é compartilhada entre as variantes.

// Props que mudam de forma com base em um discriminante "variant"
type AlertProps =
  | { variant: "success"; message: string }
  | { variant: "error"; message: string; retryAction: () => void }
  | { variant: "loading" };
 
function Alert(props: AlertProps) {
  switch (props.variant) {
    case "success":
      return <div className="alert-success">{props.message}</div>;
    case "error":
      return (
        <div className="alert-error">
          <p>{props.message}</p>
          <button onClick={props.retryAction}>Tentar Novamente</button>
        </div>
      );
    case "loading":
      return <div className="alert-loading">Carregando...</div>;
  }
}
 
// Uso
<Alert variant="success" message="Salvo!" />
<Alert variant="error" message="Falhou" retryAction={() => refetch()} />
<Alert variant="loading" />

// Helper de verificação exaustiva
function assertNever(value: never): never {
  throw new Error(`Valor inesperado: ${value}`);
}
 
function getStatusColor(props: AlertProps): string {
  switch (props.variant) {
    case "success": return "green";
    case "error": return "red";
    case "loading": return "gray";
    default: return assertNever(props);
    // Se você adicionar uma nova variante e esquecer de tratá-la,
    // o TypeScript dará erro nesta linha.
  }
}

Análise Detalhada

Como Funciona

Uma união discriminada tem um campo literal comum (o "discriminante") que o TypeScript usa para estreitar o tipo. Em AlertProps, o discriminante é variant.
Dentro de um bloco switch ou if que verifica o discriminante, o TypeScript estreita o tipo para o membro específico da união. No caso "error", props.retryAction está disponível porque o TypeScript sabe que props é { variant: "error"; message: string; retryAction: () => void }.
O padrão assertNever captura casos ausentes em tempo de compilação. Se você adicionar uma nova variante à união, mas esquecer de tratá-la no switch, o TypeScript dará erro porque a nova variante de tipo não é atribuível a never.
Uniões discriminadas são mais seguras em termos de tipo do que props opcionais porque tornam estados impossíveis irrepresentáveis. Você não pode passar retryAction para um alerta "success".

Variações

Padrão de dados assíncronos:

type AsyncData<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };
 
function UserProfile({ state }: { state: AsyncData<User> }) {
  switch (state.status) {
    case "idle":
      return null;
    case "loading":
      return <Spinner />;
    case "success":
      return <div>{state.data.name}</div>;
    case "error":
      return <div>Erro: {state.error.message}</div>;
  }
}

União de campo de formulário:

type FormField =
  | { type: "text"; label: string; placeholder?: string }
  | { type: "select"; label: string; options: string[] }
  | { type: "checkbox"; label: string; checked: boolean };
 
function FormFieldComponent({ field }: { field: FormField }) {
  switch (field.type) {
    case "text":
      return <input type="text" placeholder={field.placeholder} />;
    case "select":
      return (
        <select>
          {field.options.map((opt) => <option key={opt}>{opt}</option>)}
        </select>
      );
    case "checkbox":
      return <input type="checkbox" defaultChecked={field.checked} />;
  }
}

Props condicionais sem um discriminante:

type ModalProps =
  | { dismissible: true; onDismiss: () => void }
  | { dismissible?: false };
 
// O TypeScript garante: se dismissible for true, onDismiss é obrigatório

Notas do TypeScript

O campo discriminante deve ser um tipo literal (literal de string, literal de número ou literal booleano). Um campo do tipo string não funciona para estreitamento.
Você pode usar o estreitamento do operador in como alternativa: if ("retryAction" in props) estreita para o membro da união que possui retryAction.
A palavra-chave satisfies pode validar que um objeto corresponde a uma união sem alargar o tipo.

Armadilhas

Desestruturar props antes do switch quebra o estreitamento. Escreva switch (props.variant) em vez de const { variant } = props; switch (variant) -- o último perde a conexão entre variant e o resto de props.
Adicionar um novo membro à união sem atualizar todas as instruções switch é um bug silencioso, a menos que você use o padrão assertNever ou habilite noFallthroughCasesInSwitch.
Uniões discriminadas só estreitam quando o TypeScript pode ver a verificação do discriminante. Extrair a verificação para uma função separada requer um predicado de tipo.
Usar default: return null em vez de assertNever não detectará casos ausentes em tempo de compilação.

Alternativas

Abordagem	Prós	Contras
Uniões discriminadas	Estados impossíveis são irrepresentáveis	Definições de tipo mais verbosas
Props opcionais	Definições de tipo mais simples	Permite combinações de props inválidas
Discriminante de enum	Constantes nomeadas, autocompletar IDE	Enums têm sobrecarga de tempo de execução, uniões de string são preferidas
Componentes polimórficos	Componente único, muitas formas	Assinaturas de tipo complexas
Componentes separados por variante	Cada componente é simples e focado	Duplicação de lógica compartilhada

FAQs

O que é uma união discriminada e qual é o "discriminante"?

Uma união discriminada é um tipo de união onde cada membro tem um campo literal comum (o discriminante).
O TypeScript usa o discriminante para estreitar o tipo dentro de blocos switch ou if.
Exemplo: em { variant: "success" } | { variant: "error" }, o discriminante é variant.

Por que as uniões discriminadas são mais seguras em termos de tipo do que props opcionais?

Elas tornam estados impossíveis irrepresentáveis.
Você não pode passar retryAction para um alerta "success" -- o sistema de tipos impede isso.
Props opcionais permitem qualquer combinação, incluindo inválidas.

O que o padrão `assertNever` faz e por que é útil?

function assertNever(value: never): never {
  throw new Error(`Valor inesperado: ${value}`);
}

Colocado no caso default de um switch, ele captura casos ausentes em tempo de compilação.
Se você adicionar um novo membro à união, mas esquecer de tratá-lo, o TypeScript dará erro porque o novo tipo não é atribuível a never.

O campo discriminante pode ser um número ou booleano, ou deve ser uma string?

O discriminante deve ser um tipo literal: literal de string, literal de número ou literal booleano.
Um tipo string ou number simples não funciona para estreitamento.
Literais de string são a escolha mais comum.

Armadilha: Por que desestruturar props antes do switch quebra o estreitamento?

Escrever const { variant } = props; switch (variant) quebra a conexão entre variant e o resto de props.
O TypeScript não consegue mais estreitar props para o membro correto da união.
Sempre use switch (props.variant) para preservar o estreitamento.

Como modelar estados de carregamento de dados assíncronos com uma união discriminada?

type AsyncData<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };

Cada status tem exatamente os campos de que precisa.
data só é acessível quando status é "success".

Você pode usar o operador `in` em vez de um campo discriminante para estreitamento?

Sim. if ("retryAction" in props) estreita para o membro da união que possui retryAction.
Isso funciona sem um campo discriminante dedicado.
Ele apenas verifica a existência da propriedade, não o tipo do valor.

Armadilha: O que acontece se você usar `default: return null` em vez de `assertNever` em um switch?

O TypeScript não detectará casos ausentes em tempo de compilação.
Novos membros da união adicionados posteriormente passarão silenciosamente para o caso padrão.
Use assertNever para obter verificação de exaustividade em tempo de compilação.

Como a palavra-chave `satisfies` funciona com uniões discriminadas?

satisfies valida que um objeto corresponde a uma união sem alargar seu tipo.
O tipo inferido preserva os valores literais específicos.
Útil para objetos de configuração que devem estar em conformidade com a forma de uma união.

Como você tipa props condicionais sem um campo discriminante?

type ModalProps =
  | { dismissible: true; onDismiss: () => void }
  | { dismissible?: false };

O TypeScript garante que onDismiss é obrigatório apenas quando dismissible é true.
Quando dismissible é false ou omitido, onDismiss não pode ser passado.

Quando você escolheria componentes separados por variante em vez de um único componente de união discriminada?

Componentes separados são mais simples e focados, sem lógica de switch.
Um único componente com uma união discriminada evita duplicar a lógica de renderização compartilhada.
Escolha com base em quanta lógica é compartilhada entre as variantes.

Discriminated Unions

Receita

Exemplo de Trabalho

Análise Detalhada

Como Funciona

Variações

Notas do TypeScript

Armadilhas

Alternativas

FAQs

Relacionado

Discriminated Unions

Receita

Exemplo de Trabalho

Análise Detalhada

Como Funciona

Variações

Notas do TypeScript

Armadilhas

Alternativas

FAQs

Relacionado

Discriminated Unions

Buscar na documentação

Discriminated Unions