Type Narrowing

Q: Como funciona o narrowing com typeof e quais tipos ele suporta?

typeof restringe para: string, number, boolean, symbol, bigint, undefined, function e object. Dentro do bloco if (typeof value === "string"), o TypeScript sabe que value é string. Ele não distingue entre arrays, datas ou outros subtipos de objeto.

Q: O que é um type guard personalizado e como escrevê-lo?

Usa a anotação de tipo de retorno param is Type. Quando a função retorna true, o TypeScript restringe o parâmetro para o tipo especificado. A correção do guard é sua responsabilidade.

Q: Qual é a diferença entre um type guard (is) e uma função de asserção (asserts)?

Um type guard restringe dentro do bloco if onde é verificado. Uma função de asserção restringe para todo o código após a chamada de asserção (não apenas dentro de um if). Funções de asserção devem lançar um erro quando a condição falha - elas não podem retornar false.

Q: Como a palavra-chave satisfies difere de uma anotação de tipo?

satisfies valida que uma expressão está em conformidade com um tipo sem alterar seu tipo inferido. Uma anotação de tipo (const x: T = ...) alarga o tipo para T. satisfies preserva tipos literais e formas específicas enquanto garante a correção.

Q: Gotcha: Por que typeof null === "object" causa problemas?

Esta é uma peculiaridade conhecida do JavaScript. Usar typeof value === "object" sozinho não exclui null. Sempre escreva value !== null && typeof value === "object" para verificações seguras de objeto.

Q: Quando usar satisfies em vez de uma anotação de tipo para objetos de configuração?

Use satisfies quando quiser validação E tipos literais preservados.

Q: Type guards podem restringir em ambos os branches if e else?

Sim. No branch else de if (isAdmin(account)), o TypeScript sabe que account é User (o outro membro da união). Isso funciona para todas as técnicas de narrowing: typeof, in, instanceof e guards personalizados.

Receita

Restrinja tipos TypeScript em tempo de execução usando type guards, funções de asserção, o operador in e a palavra-chave satisfies. Escreva código que forneça ao TypeScript informações suficientes para inferir tipos precisos em cada branch.

Exemplo de Trabalho

// typeof narrowing
function formatValue(value: string | number | boolean) {
  if (typeof value === "string") {
    return value.toUpperCase(); // TypeScript sabe: string
  }
  if (typeof value === "number") {
    return value.toFixed(2); // TypeScript sabe: number
  }
  return value ? "Yes" : "No"; // TypeScript sabe: boolean
}
 
// Custom type guard com predicado "is"
type User = { kind: "user"; name: string; email: string };
type Admin = { kind: "admin"; name: string; permissions: string[] };
type Account = User | Admin;
 
function isAdmin(account: Account): account is Admin {
  return account.kind === "admin";
}
 
function AccountBadge({ account }: { account: Account }) {
  if (isAdmin(account)) {
    return <span>Admin: {account.permissions.length} permissões</span>;
  }
  return <span>Usuário: {account.email}</span>;
}

// "in" operator narrowing
function renderAccount(account: Account) {
  if ("permissions" in account) {
    // TypeScript estreita para Admin
    return <div>{account.permissions.join(", ")}</div>;
  }
  // TypeScript estreita para User
  return <div>{account.email}</div>;
}

// palavra-chave "satisfies" - valida sem alargar
const ROUTES = {
  home: "/",
  about: "/about",
  contact: "/contact",
} satisfies Record<string, string>;
 
// O tipo é preservado como { home: "/"; about: "/about"; contact: "/contact" }
// Não alargado para Record<string, string>
type RouteKey = keyof typeof ROUTES; // "home" | "about" | "contact"

Mergulho Profundo

Como Funciona

typeof narrowing funciona para tipos primitivos: string, number, boolean, symbol, bigint, undefined, function e object.
Type guards personalizados usam a anotação de tipo de retorno param is Type. Quando a função retorna true, o TypeScript restringe o parâmetro para Type no escopo de chamada.
O operador in restringe com base na existência da propriedade. "email" in account restringe para os membros da união que possuem uma propriedade email.
instanceof restringe instâncias de classe: if (error instanceof TypeError) restringe para TypeError.
satisfies valida que uma expressão está em conformidade com um tipo sem alterar seu tipo inferido. Isso preserva tipos literais e formas específicas, garantindo a correção.
Funções de asserção usam asserts param is Type. Elas lançam um erro se a condição for falsa e restringem o tipo para todo o código subsequente (não apenas para o bloco if).

Variações

Função de asserção:

function assertIsString(value: unknown): asserts value is string {
  if (typeof value !== "string") {
    throw new Error(`Esperado string, obtido ${typeof value}`);
  }
}
 
function processInput(input: unknown) {
  assertIsString(input);
  // TypeScript sabe que input é string a partir daqui
  console.log(input.toUpperCase());
}

Narrowing com Array.isArray:

function renderItems(data: string | string[]) {
  if (Array.isArray(data)) {
    return <ul>{data.map((item) => <li key={item}>{item}</li>)}</ul>;
  }
  return <p>{data}</p>;
}

Narrowing de união discriminada (switch):

type AsyncState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };
 
function renderState<T>(state: AsyncState<T>, renderData: (data: T) => React.ReactNode) {
  switch (state.status) {
    case "idle":
      return null;
    case "loading":
      return <Spinner />;
    case "success":
      return renderData(state.data); // Estreitado: data existe
    case "error":
      return <ErrorMessage error={state.error} />; // Estreitado: error existe
  }
}

satisfies com objetos de configuração:

type ColorConfig = Record<string, { bg: string; text: string }>;
 
const THEME = {
  primary: { bg: "#3b82f6", text: "#ffffff" },
  danger: { bg: "#ef4444", text: "#ffffff" },
  success: { bg: "#22c55e", text: "#ffffff" },
} satisfies ColorConfig;
 
// THEME.primary é totalmente tipado com valores literais
// THEME.nonExistent geraria um erro

Notas do TypeScript

Type guards restringem em ambos os branches if e else. No else de isAdmin(account), o TypeScript sabe que account é User.
satisfies foi adicionado no TypeScript 4.9. É especialmente valioso para objetos de configuração, mapas de rotas e definições de constantes.
Funções de asserção restringem todo o código após a asserção, não apenas dentro de um bloco if. Isso as torna poderosas para validação antecipada no topo de uma função.
Verificações nulas (if (x), if (x != null)) excluem null e undefined, mas também excluem valores falsy como 0 e "". Use != null para restrição precisa de null/undefined.

Armadilhas

Type guards personalizados colocam a correção sobre você. O TypeScript confia no seu predicado is. Se você escrever um guard com defeito, o TypeScript estará errado sobre o tipo restringido.
typeof null === "object" é uma peculiaridade do JavaScript. Use value !== null && typeof value === "object" para verificações de objeto.
Funções de asserção devem lançar um erro (não retornar false) quando a condição falha. O TypeScript depende da função nunca retornar normalmente no caso negativo.
Desestruturar antes de restringir quebra a conexão. const { status } = state; if (status === "success") { state.data } não restringe state à variante de sucesso. Use state.status diretamente.

Alternativas

Abordagem	Prós	Contras
Type guard personalizado (`is`)	Reutilizável, legível, explícito	A correção do guard é sua responsabilidade
Operador `in`	Nenhuma função auxiliar necessária	Verifica apenas a existência da propriedade, não o tipo do valor
`instanceof`	Embutido no JavaScript	Funciona apenas com classes, não com interfaces
`satisfies`	Valida sem alargar	Não cria um tipo reutilizável
Função de asserção (`asserts`)	Restringe todo o código subsequente	Deve lançar um erro, não pode retornar false
Zod `.parse()`	Segurança em tempo de execução + tempo de compilação	Dependência externa

FAQs

O que é type narrowing em TypeScript?

O processo de refinar um tipo amplo para um mais específico dentro de um bloco de código.
O TypeScript rastreia o narrowing através da análise de fluxo de controle (if, switch, typeof, in, etc.).
Após o narrowing, você pode acessar propriedades específicas do tipo restringido sem erros.

Como funciona o narrowing com `typeof` e quais tipos ele suporta?

typeof restringe para: string, number, boolean, symbol, bigint, undefined, function e object.
Dentro do bloco if (typeof value === "string"), o TypeScript sabe que value é string.
Ele não distingue entre arrays, datas ou outros subtipos de objeto.

O que é um type guard personalizado e como escrevê-lo?

function isAdmin(account: Account): account is Admin {
  return account.kind === "admin";
}

Usa a anotação de tipo de retorno param is Type.
Quando a função retorna true, o TypeScript restringe o parâmetro para o tipo especificado.
A correção do guard é sua responsabilidade.

Qual é a diferença entre um type guard (`is`) e uma função de asserção (`asserts`)?

Um type guard restringe dentro do bloco if onde é verificado.
Uma função de asserção restringe para todo o código após a chamada de asserção (não apenas dentro de um if).
Funções de asserção devem lançar um erro quando a condição falha - elas não podem retornar false.

Como a palavra-chave `satisfies` difere de uma anotação de tipo?

satisfies valida que uma expressão está em conformidade com um tipo sem alterar seu tipo inferido.
Uma anotação de tipo (const x: T = ...) alarga o tipo para T.
satisfies preserva tipos literais e formas específicas enquanto garante a correção.

Gotcha: Por que `typeof null === "object"` causa problemas?

Esta é uma peculiaridade conhecida do JavaScript.
Usar typeof value === "object" sozinho não exclui null.
Sempre escreva value !== null && typeof value === "object" para verificações seguras de objeto.

Como o operador `in` restringe tipos?

if ("permissions" in account) {
  // TypeScript restringe para o membro da união que tem "permissions"
  account.permissions; // OK
}

Restringe com base na existência da propriedade, não no valor da propriedade.
Nenhuma função auxiliar necessária, mas menos preciso que um type guard personalizado.

Gotcha: Por que desestruturar antes de restringir quebra a inferência de tipo?

const { status } = state; if (status === "success") { state.data } falha porque o TypeScript perde a conexão entre status e state.
Use state.status diretamente na verificação para manter o narrowing.
Este é um erro comum com uniões discriminadas.

Quando usar `satisfies` em vez de uma anotação de tipo para objetos de configuração?

// Com satisfies: preserva tipos literais
const ROUTES = {
  home: "/",
  about: "/about",
} satisfies Record<string, string>;
// Tipo: { home: "/"; about: "/about" }
 
// Com anotação: alarga para Record<string, string>
const ROUTES2: Record<string, string> = { home: "/", about: "/about" };

Use satisfies quando quiser validação E tipos literais preservados.

Type guards podem restringir em ambos os branches `if` e `else`?

Sim. No branch else de if (isAdmin(account)), o TypeScript sabe que account é User (o outro membro da união).
Isso funciona para todas as técnicas de narrowing: typeof, in, instanceof e guards personalizados.

O que `Array.isArray()` restringe?

function renderItems(data: string | string[]) {
  if (Array.isArray(data)) {
    return data.map((item) => item); // data é string[]
  }
  return data; // data é string
}

Restringe o tipo para a variante de array da união.
Funciona como um type guard embutido reconhecido pelo TypeScript.

// typeof narrowing
function formatValue(value: string | number | boolean) {
  if (typeof value === "string") {
    return value.toUpperCase(); // TypeScript sabe: string
  }
  if (typeof value === "number") {
    return value.toFixed(2); // TypeScript sabe: number
  }
  return value ? "Yes" : "No"; // TypeScript sabe: boolean
}
 
// Custom type guard com predicado "is"
type User = { kind: "user"; name: string; email: string };
type Admin = { kind: "admin"; name: string; permissions: string[] };
type Account = User | Admin;
 
function isAdmin(account: Account): account is Admin {
  return account.kind === "admin";
}
 
function AccountBadge({ account }: { account: Account }) {
  if (isAdmin(account)) {
    return <span>Admin: {account.permissions.length} permissões</span>;
  }
  return <span>Usuário: {account.email}</span>;
}

// "in" operator narrowing
function renderAccount(account: Account) {
  if ("permissions" in account) {
    // TypeScript estreita para Admin
    return <div>{account.permissions.join(", ")}</div>;
  }
  // TypeScript estreita para User
  return <div>{account.email}</div>;
}

// palavra-chave "satisfies" - valida sem alargar
const ROUTES = {
  home: "/",
  about: "/about",
  contact: "/contact",
} satisfies Record<string, string>;
 
// O tipo é preservado como { home: "/"; about: "/about"; contact: "/contact" }
// Não alargado para Record<string, string>
type RouteKey = keyof typeof ROUTES; // "home" | "about" | "contact"

Mergulho Profundo

Como Funciona

typeof narrowing funciona para tipos primitivos: string, number, boolean, symbol, bigint, undefined, function e object.
Type guards personalizados usam a anotação de tipo de retorno param is Type. Quando a função retorna true, o TypeScript restringe o parâmetro para Type no escopo de chamada.
O operador in restringe com base na existência da propriedade. "email" in account restringe para os membros da união que possuem uma propriedade email.
instanceof restringe instâncias de classe: if (error instanceof TypeError) restringe para TypeError.
satisfies valida que uma expressão está em conformidade com um tipo sem alterar seu tipo inferido. Isso preserva tipos literais e formas específicas, garantindo a correção.
Funções de asserção usam asserts param is Type. Elas lançam um erro se a condição for falsa e restringem o tipo para todo o código subsequente (não apenas para o bloco if).

Variações

Função de asserção:

function assertIsString(value: unknown): asserts value is string {
  if (typeof value !== "string") {
    throw new Error(`Esperado string, obtido ${typeof value}`);
  }
}
 
function processInput(input: unknown) {
  assertIsString(input);
  // TypeScript sabe que input é string a partir daqui
  console.log(input.toUpperCase());
}

Narrowing com Array.isArray:

function renderItems(data: string | string[]) {
  if (Array.isArray(data)) {
    return <ul>{data.map((item) => <li key={item}>{item}</li>)}</ul>;
  }
  return <p>{data}</p>;
}

Narrowing de união discriminada (switch):

type AsyncState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };
 
function renderState<T>(state: AsyncState<T>, renderData: (data: T) => React.ReactNode) {
  switch (state.status) {
    case "idle":
      return null;
    case "loading":
      return <Spinner />;
    case "success":
      return renderData(state.data); // Estreitado: data existe
    case "error":
      return <ErrorMessage error={state.error} />; // Estreitado: error existe
  }
}

satisfies com objetos de configuração:

type ColorConfig = Record<string, { bg: string; text: string }>;
 
const THEME = {
  primary: { bg: "#3b82f6", text: "#ffffff" },
  danger: { bg: "#ef4444", text: "#ffffff" },
  success: { bg: "#22c55e", text: "#ffffff" },
} satisfies ColorConfig;
 
// THEME.primary é totalmente tipado com valores literais
// THEME.nonExistent geraria um erro

Notas do TypeScript

Type guards restringem em ambos os branches if e else. No else de isAdmin(account), o TypeScript sabe que account é User.
satisfies foi adicionado no TypeScript 4.9. É especialmente valioso para objetos de configuração, mapas de rotas e definições de constantes.
Funções de asserção restringem todo o código após a asserção, não apenas dentro de um bloco if. Isso as torna poderosas para validação antecipada no topo de uma função.
Verificações nulas (if (x), if (x != null)) excluem null e undefined, mas também excluem valores falsy como 0 e "". Use != null para restrição precisa de null/undefined.

Armadilhas

Type guards personalizados colocam a correção sobre você. O TypeScript confia no seu predicado is. Se você escrever um guard com defeito, o TypeScript estará errado sobre o tipo restringido.
typeof null === "object" é uma peculiaridade do JavaScript. Use value !== null && typeof value === "object" para verificações de objeto.
Funções de asserção devem lançar um erro (não retornar false) quando a condição falha. O TypeScript depende da função nunca retornar normalmente no caso negativo.
Desestruturar antes de restringir quebra a conexão. const { status } = state; if (status === "success") { state.data } não restringe state à variante de sucesso. Use state.status diretamente.

Alternativas

Abordagem	Prós	Contras
Type guard personalizado (`is`)	Reutilizável, legível, explícito	A correção do guard é sua responsabilidade
Operador `in`	Nenhuma função auxiliar necessária	Verifica apenas a existência da propriedade, não o tipo do valor
`instanceof`	Embutido no JavaScript	Funciona apenas com classes, não com interfaces
`satisfies`	Valida sem alargar	Não cria um tipo reutilizável
Função de asserção (`asserts`)	Restringe todo o código subsequente	Deve lançar um erro, não pode retornar false
Zod `.parse()`	Segurança em tempo de execução + tempo de compilação	Dependência externa

FAQs

O que é type narrowing em TypeScript?

O processo de refinar um tipo amplo para um mais específico dentro de um bloco de código.
O TypeScript rastreia o narrowing através da análise de fluxo de controle (if, switch, typeof, in, etc.).
Após o narrowing, você pode acessar propriedades específicas do tipo restringido sem erros.

Como funciona o narrowing com `typeof` e quais tipos ele suporta?

typeof restringe para: string, number, boolean, symbol, bigint, undefined, function e object.
Dentro do bloco if (typeof value === "string"), o TypeScript sabe que value é string.
Ele não distingue entre arrays, datas ou outros subtipos de objeto.

O que é um type guard personalizado e como escrevê-lo?

function isAdmin(account: Account): account is Admin {
  return account.kind === "admin";
}

Usa a anotação de tipo de retorno param is Type.
Quando a função retorna true, o TypeScript restringe o parâmetro para o tipo especificado.
A correção do guard é sua responsabilidade.

Qual é a diferença entre um type guard (`is`) e uma função de asserção (`asserts`)?

Um type guard restringe dentro do bloco if onde é verificado.
Uma função de asserção restringe para todo o código após a chamada de asserção (não apenas dentro de um if).
Funções de asserção devem lançar um erro quando a condição falha - elas não podem retornar false.

Como a palavra-chave `satisfies` difere de uma anotação de tipo?

satisfies valida que uma expressão está em conformidade com um tipo sem alterar seu tipo inferido.
Uma anotação de tipo (const x: T = ...) alarga o tipo para T.
satisfies preserva tipos literais e formas específicas enquanto garante a correção.

Gotcha: Por que `typeof null === "object"` causa problemas?

Esta é uma peculiaridade conhecida do JavaScript.
Usar typeof value === "object" sozinho não exclui null.
Sempre escreva value !== null && typeof value === "object" para verificações seguras de objeto.

Como o operador `in` restringe tipos?

if ("permissions" in account) {
  // TypeScript restringe para o membro da união que tem "permissions"
  account.permissions; // OK
}

Restringe com base na existência da propriedade, não no valor da propriedade.
Nenhuma função auxiliar necessária, mas menos preciso que um type guard personalizado.

Gotcha: Por que desestruturar antes de restringir quebra a inferência de tipo?

const { status } = state; if (status === "success") { state.data } falha porque o TypeScript perde a conexão entre status e state.
Use state.status diretamente na verificação para manter o narrowing.
Este é um erro comum com uniões discriminadas.

Quando usar `satisfies` em vez de uma anotação de tipo para objetos de configuração?

// Com satisfies: preserva tipos literais
const ROUTES = {
  home: "/",
  about: "/about",
} satisfies Record<string, string>;
// Tipo: { home: "/"; about: "/about" }
 
// Com anotação: alarga para Record<string, string>
const ROUTES2: Record<string, string> = { home: "/", about: "/about" };

Use satisfies quando quiser validação E tipos literais preservados.

Type guards podem restringir em ambos os branches `if` e `else`?

Sim. No branch else de if (isAdmin(account)), o TypeScript sabe que account é User (o outro membro da união).
Isso funciona para todas as técnicas de narrowing: typeof, in, instanceof e guards personalizados.

O que `Array.isArray()` restringe?

function renderItems(data: string | string[]) {
  if (Array.isArray(data)) {
    return data.map((item) => item); // data é string[]
  }
  return data; // data é string
}

Restringe o tipo para a variante de array da união.
Funciona como um type guard embutido reconhecido pelo TypeScript.

Type Narrowing

Receita

Exemplo de Trabalho

Mergulho Profundo

Como Funciona

Variações

Notas do TypeScript

Armadilhas

Alternativas

FAQs

Relacionado

Type Narrowing

Receita

Exemplo de Trabalho

Mergulho Profundo

Como Funciona

Variações

Notas do TypeScript

Armadilhas

Alternativas

FAQs

Relacionado

Type Narrowing

Buscar na documentação

Type Narrowing