Tipos em TypeScript: string, number, boolean e mais

Os tipos do TypeScript descrevem que tipo de valor uma variável pode guardar. Você escreve o tipo depois de dois pontos, let name: string, e o compilador rejeita qualquer código que coloque ali um valor do tipo errado. Os tipos básicos são os sete primitivos do JavaScript mais os tipos de objeto para arrays e objetos.

let title: string = "TypeScript";
let version: number = 7;
let isStrict: boolean = true;
let big: bigint = 9007199254740993n;
let id: symbol = Symbol("id");
let nothing: null = null;
let notSet: undefined = undefined;

let scores: number[] = [90, 72, 85];
let user: { name: string; age: number } = { name: "Ada", age: 36 };

console.log(title, version, isStrict, big, id);
console.log(nothing, notSet);
console.log(scores, user);

As anotações são verificadas em tempo de compilação e depois removidas. O programa que roda é JavaScript puro.

Os tipos primitivos

Os nomes dos tipos são minúsculos. Em tempo de execução, typeof retorna as mesmas palavras para a maioria deles, então typeof x === "number" é a forma de verificar o tipo primitivo de um valor enquanto o programa roda.

Anotações de tipo

Uma anotação é : Type depois de uma variável, de um parâmetro ou da lista de parâmetros de uma função. Os parâmetros são onde as anotações mais importam, porque o TypeScript não tem como adivinhar o que quem chama vai passar.

function describe(name: string, age: number, admin: boolean): string {
    return `${name} (${age})${admin ? " [admin]" : ""}`;
}

let label: string = describe("Ada", 36, true);
console.log(label); // Ada (36) [admin]

// Without an annotation, TypeScript infers the type from the value:
let count = 10; // count: number
count = count + 1;
console.log(count); // 11

Quando a variável é inicializada na mesma linha, a anotação costuma ser redundante: let count = 10 já tem o tipo number. As regras para omitir tipos estão na página de inferência de tipos.

Um tipo errado é um erro de compilação

Atribua um valor do tipo errado e o compilador para antes de qualquer coisa rodar:

// This does not compile: a string is not a number.
let port: number = 8080;
port = "3000";
console.log(port);

O compilador mostra:

index.ts(3,1): error TS2322: Type 'string' is not assignable to type 'number'.

A correção é converter o valor, port = Number("3000"), ou mudar a anotação se a variável realmente deve guardar texto.

number: não existe tipo inteiro

O JavaScript guarda todo número como um valor de ponto flutuante de 64 bits, por isso o TypeScript tem um único tipo number. Inteiros são exatos até Number.MAX_SAFE_INTEGER (2 ** 53 - 1). Acima disso, use bigint.

let price: number = 19.99;
let quantity: number = 3; // also number: no int type

console.log(Number.isInteger(quantity)); // true
console.log(Number.isInteger(price));    // false
console.log(Math.trunc(7 / 2));          // 3 (integer division)
console.log(0.1 + 0.2);                  // 0.30000000000000004

console.log(Number.MAX_SAFE_INTEGER);     // 9007199254740991
console.log(Number.MAX_SAFE_INTEGER + 2); // 9007199254740992 (wrong)

let exact: bigint = 9007199254740991n + 2n;
console.log(exact); // 9007199254740993n

// @ts-expect-error: bigint and number cannot be mixed
const mixed = () => exact + 1;
console.log(exact + BigInt(1), Number(exact)); // 9007199254740994n 9007199254740992

bigint e number não se misturam: exact + 1 é um erro de compilação (TS2365: Operator '+' cannot be applied to types 'bigint' and '1'., em que '1' é o tipo literal do 1) e, se chegasse a rodar, também seria um TypeError em tempo de execução. Converta um dos lados explicitamente com BigInt(1) ou Number(exact), sabendo que Number arredonda valores fora da faixa segura.

Se você quer um tipo que aceite só números inteiros, o TypeScript não consegue expressar isso para valores arbitrários. Valide com Number.isInteger no ponto em que o valor entra no seu programa.

boolean

boolean tem exatamente dois valores, true e false. Valores que são apenas truthy (1, "yes") não são booleanos, então converta-os com Boolean(x) ou x !== 0.

let loggedIn: boolean = false;
const items: string[] = ["a", "b"];

const hasItems: boolean = items.length > 0;
const hasName: boolean = Boolean("Ada");

console.log(loggedIn, hasItems, hasName); // false true true

null e undefined

Com strict ativado (o padrão desde o TypeScript 6.0), null e undefined são tipos separados e não fazem parte de string, number nem de nenhum outro tipo. Uma variável que pode estar vazia declara isso com uma union:

let nickname: string | undefined;
console.log(nickname); // undefined

nickname = "Ace";
console.log(nickname.toUpperCase()); // ACE

let middleName: string | null = null;
console.log(middleName ?? "(none)"); // (none)

Ler uma propriedade de um valor que pode ser undefined é um erro de compilação até você fazer a verificação. A página de null e undefined explica as verificações, ?. e ??.

Arrays e objetos em resumo

Tudo o que não é primitivo é um tipo de objeto. As três formas que você encontra primeiro:

let tags: string[] = ["ts", "js"];               // array of strings
let point: { x: number; y: number } = { x: 1, y: 2 }; // object with two number properties
let greet: (name: string) => string = (n) => `hi ${n}`; // function type

Cada uma tem sua própria página: arrays, tuplas (arrays de tamanho fixo), tipos de objeto e tipos de função.

string, number, boolean vs String, Number, Boolean

Os nomes com inicial maiúscula são os tipos dos objetos wrapper do JavaScript (new String("x")), não dos valores comuns. Anote com os nomes minúsculos.

// This does not compile: String (the wrapper) is not string (the primitive).
const wrapped: String = "text";
const plain: string = wrapped;
console.log(plain);

index.ts(3,7): error TS2322: Type 'String' is not assignable to type 'string'.
  'string' is a primitive, but 'String' is a wrapper object. Prefer using 'string' when possible.

Troque String por string na primeira linha e o bloco roda. O mesmo vale para Number, Boolean, Symbol e BigInt. (Object é outro caso: aceita quase qualquer valor, primitivos incluídos; veja tipos de objeto.)

Outros tipos nativos

Mais alguns tipos aparecem logo no começo. Cada um tem sua própria página.