PromptWake
← Blog
·10 blog.minutes

TypeScript Moderno: Padrões e Práticas para 2026

Da configuração estrita a clientes de API type-safe — os padrões TypeScript que separam código de nível de produção de projetos de brinquedo em 2026.

TypeScript evoluiu mais rápido que a maioria dos ecossistemas consegue acompanhar. Cada lançamento traz nova sintaxe, verificações mais rigorosas e padrões que reescrevem o que parece idiomático. A diferença entre código TypeScript que meramente compila e código que genuinamente aproveita o sistema de tipos é vasta — e essa lacuna determina se seus tipos são documentação ou ruído.

Este artigo cobre os padrões que mais importam para TypeScript em produção em 2026. Estes não são exercícios acadêmicos. São as práticas que tornam bases de código grandes mais seguras, APIs mais difíceis de usar incorretamente e refatoração menos aterrorizante. Cada exemplo vem de padrões reais usados em sistemas de produção que lidam com milhões de requisições.

A Fundação: Configuração TypeScript para 2026

A decisão mais impactante que você toma sobre a qualidade do TypeScript não está no seu código — está no seu tsconfig.json. A linha de base foi além de strict: true. Em 2026, uma configuração de nível de produção deve habilitar verificações que eram opt-in ou experimentais em versões anteriores.

// tsconfig.json — the 2026 baseline
{
  "compilerOptions": {
    "strict": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true,
    "noPropertyAccessFromIndexSignature": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

Cada flag elimina uma classe de bugs. exactOptionalPropertyTypes previne o erro comum onde ?: string | undefined é atribuído undefined explicitamente — a distinção entre ausente e presente-mas-undefined importa em limites de API. noUncheckedIndexedAccess força você a lidar com undefined para todo acesso a objeto com chave dinâmica, o que pega crashes em tempo de execução antes de irem para produção. verbatimModuleSyntax garante que sua resolução de módulos corresponda ao runtime, eliminando as incompatibilidades silenciosas que quebram projetos ESM em produção.

Equipes que adotam esta configuração relatam significativamente menos incidentes de produção relacionados a referências nulas e propriedades undefined. A sobrecarga de lidar com essas verificações extras de undefined antecipadamente é trivial comparada a depurar um crash porque uma resposta de API estava faltando um campo que você assumiu que existia.

Uniões Discriminadas — Seu Padrão Mais Poderoso

Uniões discriminadas são o padrão mais impactante no TypeScript. Elas modelam estados explicitamente, tornam estados ilegais irrepresentáveis e dão ao compilador a informação que ele precisa para impor tratamento exaustivo. Se você não as está usando para qualquer dado que tem múltiplas formas, está lutando contra o sistema de tipos em vez de deixá-lo trabalhar para você.

type ApiState<S, E = Error> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: S }
  | { status: "error"; error: E };

// Exhaustive match — if you add a status, this breaks at compile time
function renderState<S>(state: ApiState<S>): string {
  switch (state.status) {
    case "idle":
      return "Awaiting input";
    case "loading":
      return "Loading...";
    case "success":
      return `Got ${JSON.stringify(state.data)}`;
    case "error":
      return `Failed: ${state.error.message}`;
  }
}

// Usage — impossible to access data on a loading state
const userState: ApiState<User> = { status: "loading" };
// userState.data — does not compile
// userState.status — narrows correctly after any check

A mágica está no estreitamento (narrowing). Quando você verifica state.status === "success", o TypeScript sabe exatamente em qual variante você está e fornece o tipo correto para cada campo nesse ramo. Isso elimina categorias inteiras de verificações defensivas que o código em tempo de execução precisaria. O compilador se torna seu conjunto de testes para transições de estado inválidas.

Para este padrão funcionar efetivamente, a propriedade discriminante (status no exemplo acima) deve ser um tipo literal, não uma string genérica. Cada variante deve ter um valor literal único. O compilador usa esse literal para discriminar entre ramos, e avisará se duas variantes tiverem o mesmo valor discriminante.

  • Sempre use uma string literal ou número como discriminante — nunca um tipo string genérico.
  • Mantenha as propriedades compartilhadas mínimas. Tudo que difere entre variantes pertence dentro do objeto da variante.
  • Combine com o tipo never para verificações de exaustividade: declare uma variável do tipo never no branch default de um switch para capturar casos não tratados em tempo de compilação.

Tipos Literais de Template e Tipos Marcados (Branded)

Tipos literais de template e tipos marcados resolvem dois problemas distintos que tipos TypeScript regulares não podem abordar. Tipos literais de template fornecem validação de string no nível de tipo. Tipos marcados fornecem tipagem nominal em um mundo estruturalmente tipado — eles permitem distinguir entre dois valores que têm a mesma forma mas significados semânticos diferentes.

// Template literal type — valid API routes are checked at compile time
type ApiRoute = `/api/${string}`;
type UserRoute = `/api/users/${string}`;

function fetchApi<T>(route: ApiRoute): Promise<T> {
  return fetch(route).then((r) => r.json());
}

// fetchApi("/invalid");       // Error: not assignable
// fetchApi("/api/users/123"); // OK

// Branded type — distinguish IDs that are both strings
type UserId = string & { __brand: "UserId" };
type OrderId = string & { __brand: "OrderId" };

function createUserId(id: string): UserId {
  return id as UserId;
}

function getUser(id: UserId): Promise<User> {
  return db.users.find(id);
}

const orderId = "ord_123" as OrderId;
// getUser(orderId); // Error: Type 'OrderId' is not assignable to type 'UserId'

Tipos literais de template brilham em qualquer sistema onde strings seguem um formato previsível. Construtores de rotas de API, geradores de classes CSS, combinadores de chaves i18n e sistemas de nomes de eventos todos se beneficiam da validação em tempo de compilação de valores de string. A sintaxe é intuitiva — você escreve um padrão com placeholders ${}, e o TypeScript valida que valores reais correspondem a esse padrão.

Tipos marcados resolvem um problema diferente. TypeScript é estruturalmente tipado, o que significa que dois tipos com formas idênticas são intercambiáveis. Isso geralmente é uma vantagem, mas se torna perigoso quando você tem IDs que são ambas strings mas representam entidades diferentes. Um UserId e um OrderId não deveriam ser intercambiáveis, mesmo que ambos sejam strings. A interseção com { __brand: "X" } cria um tipo fantasma que existe apenas em tempo de compilação — não tem custo de runtime.

Tipos marcados são o mais próximo que o TypeScript chega da tipagem nominal sem ferramentas adicionais. Uma interseção com uma propriedade fantasma pode prevenir a classe de bugs onde o ID errado é passado para a função errada.

O Operador satisfies — Inferência Sem Sacrifício

Antes do satisfies, desenvolvedores TypeScript enfrentavam um dilema ao definir constantes que precisavam corresponder a um tipo enquanto preservavam seus valores literais. Você podia anotar o tipo e perder a inferência estreita, ou omitir a anotação e perder a validação. O operador satisfies remove esse tradeoff completamente.

type ColorPalette = {
  primary: string;
  secondary: string;
  accent: string;
};

// Before satisfies — loses literal types
const paletteOld: ColorPalette = {
  primary: "#0f0f0f",  // type is string, not "#0f0f0f"
  secondary: "#ffffff",
  accent: "#0055ff",
};

// After satisfies — validates shape, keeps literals
const palette = {
  primary: "#0f0f0f",  // type is "#0f0f0f"
  secondary: "#ffffff",
  accent: "#0055ff",
} satisfies ColorPalette;

// palette.primary; // type is "#0f0f0f", not string

// Works with complex types too
type EventMap = {
  click: { x: number; y: number };
  focus: { target: string };
  input: { value: string };
};

const handlers = {
  click: (e: { x: number; y: number }) => console.log(e.x, e.y),
  focus: (e: { target: string }) => console.log(e.target),
} satisfies Partial<Record<keyof EventMap, Function>>;

// handlers.click — retains the parameter type from the implementation
// handlers.input — missing, but satisfies allows Partial
// Add input handler later without breaking anything

O operador satisfies é mais valioso em objetos de configuração, manipuladores de eventos e estruturas de mapeamento onde você quer segurança de tipo na forma mas precisa dos tipos mais estreitos possíveis para os valores. Ele substitui uma constelação de workarounds — asserções as const combinadas com anotações de tipo, casts de tipo redundantes e funções de validação separadas — por uma única palavra-chave.

Padrões Genéricos e Clientes de API Type-Safe

Genéricos em TypeScript são fáceis de usar para casos simples — Array<T>, Promise<T> — mas se tornam verdadeiramente poderosos quando você combina restrições, tipos condicionais e inferência em uma única assinatura de função. A aplicação mais prática de genéricos avançados é construir clientes de API type-safe que eliminam categorias inteiras de erros de runtime.

// Type-safe API client
import { z } from "zod";

// Infer the output type from a Zod schema
type InferSchema<T extends z.ZodTypeAny> = T["_output"];

// Route definitions with path params and response schema
type RouteDef = {
  path: string;
  method: "GET" | "POST" | "PUT" | "DELETE";
  params?: Record<string, string>;
  body?: unknown;
};

class ApiClient {
  constructor(private base: string) {}

  get<
    TPath extends string,
    TSchema extends z.ZodTypeAny,
  >(
    path: TPath,
    schema: TSchema,
    ...[params]: TPath extends `${string}:${infer _}/${string}`
      ? [Record<string, string>]
      : TPath extends `${string}:${infer _}`
        ? [Record<string, string>]
        : [Record<string, string>?]
  ): Promise<InferSchema<TSchema>> {
    const resolved = params
      ? Object.entries(params).reduce(
          (p, [k, v]) => p.replace(`:${k}`, v),
          path
        )
      : path;
    return fetch(`${this.base}${resolved}`)
      .then((r) => r.json())
      .then((d) => schema.parse(d) as InferSchema<TSchema>);
  }
}

const api = new ApiClient("https://api.example.com");

const userSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
});

// api.get("/users/:id", userSchema, { id: "123" });
// Result type: { id: string; name: string; email: string }
// If params are required but missing, type error at compile time

O padrão ApiClient combina várias técnicas avançadas. Tipos condicionais com infer detectam se a rota contém parâmetros de caminho e exigem condicionalmente o argumento params. O schema de resposta é analisado em runtime com Zod e inferido em tempo de compilação, então o tipo de retorno está sempre correto. Se a API mudar sua forma de resposta, você atualiza o schema e o compilador encontra todo consumidor que quebra.

Este padrão escala para centenas de endpoints sem cerimônia. Cada endpoint é apenas uma string de caminho e um schema Zod. A infraestrutura genérica cuida do resto — resolução de parâmetros de caminho, validação de resposta e inferência de tipo. Equipes usando este padrão relatam eliminar a maioria dos bugs de integração entre frontend e backend.

  • Combine schemas Zod ou ArkType com wrappers de fetch genéricos para segurança de tipo ponta a ponta através do limite de rede.
  • Use tipos condicionais com infer para tornar argumentos obrigatórios ou opcionais com base na estrutura da rota.
  • Retorne tipos marcados do seu cliente de API para que chamadores não possam acidentalmente trocar IDs entre diferentes tipos de entidade.

Padrões de Tratamento de Erros e Aumento de Módulo

O tratamento de erros é onde a maioria das bases de código TypeScript recorre a any e finge que o problema não existe. O padrão Result — inspirado por Rust e programação funcional — traz erros para o sistema de tipos para que o compilador exija que todo caminho de erro seja tratado. O aumento de módulo estende esta abordagem para tipos de terceiros, permitindo adicionar segurança de tipo a bibliotecas que fornecem definições de tipo incompletas ou excessivamente permissivas.

// Result type — errors are part of the return type, not thrown

type Result<T, E = Error> =
  | { ok: true; value: T }
  | { ok: false; error: E };

async function fetchUser(id: UserId): Promise<Result<User, ApiError>> {
  try {
    const res = await fetch(`/api/users/${id}`);
    if (!res.ok) {
      return { ok: false, error: await ApiError.fromResponse(res) };
    }
    return { ok: true, value: await res.json() };
  } catch (err) {
    return { ok: false, error: new ApiError("network", String(err)) };
  }
}

// Consumer must handle both branches — compiler enforces it
const result = await fetchUser(userId);
if (result.ok) {
  console.log(result.value.name); // result.value is User
} else {
  console.error(result.error.code); // result.error is ApiError
}

// --- Module augmentation for third-party types ---

// express-session types are incomplete — augment them
declare module "express-session" {
  interface SessionData {
    userId?: string;
    role: "admin" | "user" | "viewer";
    permissions: string[];
  }
}

// Now req.session.role narrows to "admin" | "user" | "viewer"
// Without augmentation, req.session.role would be any

O padrão Result força o tratamento explícito de erros em cada ponto de chamada. Não há como ignorar silenciosamente uma operação falha — o compilador exige que você verifique result.ok antes de acessar result.value. Isso elimina o try-catch esquecido que é a fonte de inúmeros incidentes de produção. O custo é um pouco mais de digitação em cada ponto de chamada, mas o benefício é que nenhum erro passa despercebido.

O aumento de módulo preenche as lacunas onde as definições de tipo de terceiros são deficientes. Muitas bibliotecas populares vêm com tipos excessivamente permissivos — funções que retornam any, parâmetros tipados como object ou propriedades ausentes em suas interfaces. Em vez de fazer cast com as ou usar @ts-ignore, declare module "nome-da-biblioteca" em um arquivo .d.ts ou .ts e adicione os tipos faltantes. As declarações se mesclam automaticamente, e toda sua base de código se beneficia da correção.

A combinação destes padrões — configuração estrita, uniões discriminadas, tipos literais de template, tipos marcados, satisfies, genéricos type-safe e tratamento explícito de erros — representa uma abordagem abrangente para TypeScript em 2026. Cada padrão é independentemente útil, mas juntos eles criam uma base de código onde o compilador detecta erros que de outra forma se tornariam incidentes de produção. O investimento em aprender esses padrões se paga muitas vezes em tempo de depuração reduzido, refatoração mais segura e APIs que são genuinamente difíceis de usar incorretamente.