Type alias em TypeScript: a palavra-chave type com exemplos

Um type alias dá nome a um tipo. Você escreve type Name = ... e, a partir daí, Name pode ser usado em qualquer lugar em que um tipo é esperado. Diferente de uma interface, um alias pode dar nome a qualquer tipo, e não só a formatos de objeto.

type UserId = string;                         // a primitive
type Point = { x: number; y: number };        // an object shape
type Status = "active" | "banned";            // a union of literals
type Pair = [string, number];                 // a tuple
type Formatter = (value: number) => string;   // a function

const id: UserId = "u_42";
const start: Point = { x: 0, y: 0 };
const current: Status = "active";
const entry: Pair = ["score", 90];
const money: Formatter = (v) => `$${v.toFixed(2)}`;

console.log(id, start, current, entry, money(3.5));
// u_42 { x: 0, y: 0 } active [ 'score', 90 ] $3.50

Aliases existem só em tempo de compilação. O JavaScript gerado não contém nenhuma dessas linhas type.

Sintaxe

type Name = SomeType;
type Name<T> = SomeTypeUsing<T>;       // generic
export type Name = SomeType;           // exported from a module

Por convenção, os nomes são em PascalCase. O lado direito é qualquer expressão de tipo, e um alias pode usar outros aliases, inclusive a si mesmo (veja os tipos recursivos mais abaixo). O alias fica disponível em todo o escopo em que é declarado, até acima da linha da declaração, porque os tipos são verificados em tempo de compilação e não executados em ordem como const ou let.

Tipos de objeto

Para um formato de objeto, um alias e uma interface se escrevem quase do mesmo jeito. O alias usa = e normalmente termina com ponto e vírgula.

type User = {
  id: number;
  name: string;
  email?: string;           // optional
  readonly createdAt: string; // cannot be reassigned
};

type Admin = User & { permissions: string[] }; // extend with an intersection

const root: Admin = {
  id: 1,
  name: "root",
  createdAt: "2024-03-15",
  permissions: ["*"],
};

console.log(`${root.name} can do ${root.permissions.join(", ")}`); // root can do *

Um alias não pode usar extends; a intersection & cumpre esse papel. A verificação de propriedades extras e as propriedades opcionais e readonly funcionam exatamente como nas interfaces. Qual dos dois escolher para formatos de objeto é assunto da página sobre interface vs type.

Unions, tuplas e funções

Estes são os casos que só um alias pode nomear, e o principal motivo de o type existir. Um alias de union lista as alternativas, um alias de tupla fixa o tamanho e os tipos dos elementos de um array, e um alias de função descreve uma assinatura.

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number };

type Span = [start: number, end: number]; // labeled tuple elements

type Transform = (shape: Shape, factor: number) => Shape;

const scale: Transform = (shape, factor) =>
  shape.kind === "circle"
    ? { kind: "circle", radius: shape.radius * factor }
    : { kind: "rect", width: shape.width * factor, height: shape.height * factor };

const r: Span = [10, 20];
console.log(scale({ kind: "circle", radius: 2 }, 3)); // { kind: 'circle', radius: 6 }
console.log(r[1] - r[0]);                              // 10

Em scale, os parâmetros não precisam de anotação: o alias Transform fornece os tipos deles. A sintaxe de tuplas está em tuplas, e o narrowing de unions na página sobre union types.

Type aliases genéricos

Type parameters fazem um único alias funcionar para muitos tipos. Eles podem ter padrões, como os parâmetros de função.

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

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0
    ? { ok: true, value: n }
    : { ok: false, error: `not an age: ${text}` };
}

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? `age ${r.value}` : r.error);
}
// age 36
// not an age: abc

Result<number> usa o padrão E = string. Aliases genéricos pequenos como type Nullable<T> = T | null ou type Dict<T> = Record<string, T> são comuns em código real. Os utility types nativos (Partial<T>, Pick<T, K>, ReturnType<F>) também são aliases genéricos, declarados na biblioteca padrão.

Aliases são nomes, não tipos novos

Um alias não cria um tipo distinto. Ele é um segundo nome para o tipo da direita, e o compilador trata os dois como idênticos. Dois aliases de string são totalmente intercambiáveis:

type UserId = string;
type OrderId = string;

function cancelOrder(id: OrderId) {
  console.log("cancelling", id);
}

const user: UserId = "u_42";
cancelOrder(user); // compiles: UserId and OrderId are both just string

Isso imprime cancelling u_42 sem erro nenhum, que é justamente o bug que um alias não consegue evitar. O alias ainda ajuda quem lê (um parâmetro tipado como OrderId diz mais que string), mas se confundir dois ids precisa ser um erro de compilação, use um branded type como string & { readonly __brand: "OrderId" }.

Type aliases recursivos

Um alias pode referenciar a si mesmo, e é assim que se descrevem árvores, listas aninhadas e JSON:

type Json =
  | string
  | number
  | boolean
  | null
  | Json[]
  | { [key: string]: Json };

type TreeNode = {
  value: number;
  children: TreeNode[];
};

function sum(node: TreeNode): number {
  return node.value + node.children.reduce((total, child) => total + sum(child), 0);
}

const tree: TreeNode = {
  value: 1,
  children: [
    { value: 2, children: [] },
    { value: 3, children: [{ value: 4, children: [] }] },
  ],
};

const payload: Json = { ok: true, items: [1, "two", null], meta: { page: 1 } };

console.log(sum(tree));               // 10
console.log(JSON.stringify(payload)); // {"ok":true,"items":[1,"two",null],"meta":{"page":1}}

O alias Json rejeita valores que o JSON não consegue representar: { when: new Date() } ou { f: undefined } atribuídos a Json são erros de compilação (TS2322).

Tipos a partir de valores: typeof

Quando um valor já existe, você pode nomear o tipo dele em vez de escrevê-lo. O operador de tipo typeof lê o tipo de uma variável, e se combina com outros operadores:

const defaults = { retries: 3, verbose: false, level: "info" };

type Options = typeof defaults;
// { retries: number; verbose: boolean; level: string }

type OptionKey = keyof typeof defaults;
// "retries" | "verbose" | "level"

function start(port: number) {
  return { port, startedAt: new Date() };
}
type Server = ReturnType<typeof start>;
// { port: number; startedAt: Date }

O valor continua sendo a única fonte da verdade: adicione uma propriedade a defaults e Options acompanha. Mais sobre isso em typeof.

Exportando e importando aliases

Aliases são exportados e importados como valores. import type deixa explícito que só um tipo é importado, então o import sempre é removido da saída JavaScript:

// shapes.ts
export type Point = { x: number; y: number };
export type Shape = { kind: "circle"; center: Point; radius: number };

// main.ts
import type { Point, Shape } from "./shapes.js";

const p: Point = { x: 1, y: 2 };