Tipos de objeto

No JavaScript, a forma fundamental de agrupar e passar dados é por meio de objetos. No TypeScript, representamos isso com tipos de objeto.

Como já vimos, eles podem ser anônimos:

ts
function greet(person: { name: string; age: number }) {
return "Hello " + person.name;
}
Try

ou podem receber um nome usando uma interface:

ts
interface Person {
name: string;
age: number;
}
 
function greet(person: Person) {
return "Hello " + person.name;
}
Try

ou um alias de tipo:

ts
type Person = {
name: string;
age: number;
};
 
function greet(person: Person) {
return "Hello " + person.name;
}
Try

Nos três exemplos acima, escrevemos funções que recebem objetos com a propriedade name (que precisa ser string) e age (que precisa ser number).

Referência rápida

Temos cheat sheets disponíveis para type e interface, caso você queira dar uma olhada rápida na sintaxe do dia a dia.

Modificadores de propriedade

Cada propriedade de um tipo de objeto pode especificar algumas coisas: o tipo, se a propriedade é opcional e se ela pode ser escrita.

Propriedades opcionais

Muitas vezes, vamos lidar com objetos que podem ter uma propriedade definida. Nesses casos, podemos marcar essas propriedades como opcionais adicionando um ponto de interrogação (?) no fim do nome delas.

ts
interface PaintOptions {
shape: Shape;
xPos?: number;
yPos?: number;
}
 
function paintShape(opts: PaintOptions) {
// ...
}
 
const shape = getShape();
paintShape({ shape });
paintShape({ shape, xPos: 100 });
paintShape({ shape, yPos: 100 });
paintShape({ shape, xPos: 100, yPos: 100 });
Try

Neste exemplo, tanto xPos quanto yPos são consideradas opcionais. Podemos escolher fornecer qualquer uma delas, então todas as chamadas de paintShape acima são válidas. Tudo o que a opcionalidade realmente diz é que, se a propriedade estiver definida, ela precisa ter um tipo específico.

Também podemos ler dessas propriedades, mas, quando fazemos isso com strictNullChecks ativado, o TypeScript avisa que elas podem ser undefined.

ts
function paintShape(opts: PaintOptions) {
let xPos = opts.xPos;
(property) PaintOptions.xPos?: number | undefined
let yPos = opts.yPos;
(property) PaintOptions.yPos?: number | undefined
// ...
}
Try

No JavaScript, mesmo que a propriedade nunca tenha sido definida, ainda podemos acessá-la: ela simplesmente vai retornar o valor undefined. Podemos tratar undefined de forma especial, verificando-o.

ts
function paintShape(opts: PaintOptions) {
let xPos = opts.xPos === undefined ? 0 : opts.xPos;
let xPos: number
let yPos = opts.yPos === undefined ? 0 : opts.yPos;
let yPos: number
// ...
}
Try

Repare que esse padrão de definir valores padrão para valores não informados é tão comum que o JavaScript tem sintaxe própria para isso.

ts
function paintShape({ shape, xPos = 0, yPos = 0 }: PaintOptions) {
console.log("x coordinate at", xPos);
(parameter) xPos: number
console.log("y coordinate at", yPos);
(parameter) yPos: number
// ...
}
Try

Aqui usamos um padrão de desestruturação para o parâmetro de paintShape e fornecemos valores padrão para xPos e yPos. Agora xPos e yPos estão certamente presentes no corpo de paintShape, mas são opcionais para quem chama paintShape.

Repare que atualmente não há como colocar anotações de tipo dentro de padrões de desestruturação. Isso acontece porque a sintaxe a seguir já tem outro significado no JavaScript.

ts
function draw({ shape: Shape, xPos: number = 100 /*...*/ }) {
render(shape);
Cannot find name 'shape'. Did you mean 'Shape'?2552Cannot find name 'shape'. Did you mean 'Shape'?
render(xPos);
Cannot find name 'xPos'.2304Cannot find name 'xPos'.
}
Try

Em um padrão de desestruturação de objeto, shape: Shape significa “pegue a propriedade shape e redefina-a localmente como uma variável chamada Shape”. Da mesma forma, xPos: number cria uma variável chamada number cujo valor é baseado no xPos do parâmetro.

Propriedades readonly

Propriedades também podem ser marcadas como readonly para o TypeScript. Embora isso não mude nenhum comportamento em tempo de execução, uma propriedade marcada como readonly não pode ser escrita durante a verificação de tipos.

ts
interface SomeType {
readonly prop: string;
}
 
function doSomething(obj: SomeType) {
// We can read from 'obj.prop'.
console.log(`prop has the value '${obj.prop}'.`);
 
// But we can't re-assign it.
obj.prop = "hello";
Cannot assign to 'prop' because it is a read-only property.2540Cannot assign to 'prop' because it is a read-only property.
}
Try

Usar o modificador readonly não implica necessariamente que um valor é totalmente imutável, ou seja, que o conteúdo interno dele não pode ser alterado. Ele significa apenas que a própria propriedade não pode ser reescrita.

ts
interface Home {
readonly resident: { name: string; age: number };
}
 
function visitForBirthday(home: Home) {
// We can read and update properties from 'home.resident'.
console.log(`Happy birthday ${home.resident.name}!`);
home.resident.age++;
}
 
function evict(home: Home) {
// But we can't write to the 'resident' property itself on a 'Home'.
home.resident = {
Cannot assign to 'resident' because it is a read-only property.2540Cannot assign to 'resident' because it is a read-only property.
name: "Victor the Evictor",
age: 42,
};
}
Try

É importante alinhar as expectativas sobre o que readonly implica. Ele é útil para sinalizar a intenção, durante o desenvolvimento, de como o TypeScript deve tratar o uso de um objeto. O TypeScript não considera se as propriedades de dois tipos são readonly ao verificar se esses tipos são compatíveis, então propriedades readonly também podem mudar por meio de aliases.

ts
interface Person {
name: string;
age: number;
}
 
interface ReadonlyPerson {
readonly name: string;
readonly age: number;
}
 
let writablePerson: Person = {
name: "Person McPersonface",
age: 42,
};
 
// works
let readonlyPerson: ReadonlyPerson = writablePerson;
 
console.log(readonlyPerson.age); // prints '42'
writablePerson.age++;
console.log(readonlyPerson.age); // prints '43'
Try

Usando modificadores de mapeamento, você pode remover os atributos readonly.

Assinaturas de índice

Às vezes você não conhece de antemão todos os nomes das propriedades de um tipo, mas conhece o formato dos valores.

Nesses casos, você pode usar uma assinatura de índice para descrever os tipos dos valores possíveis, por exemplo:

ts
interface StringArray {
[index: number]: string;
}
 
const myArray: StringArray = getStringArray();
const secondItem = myArray[1];
const secondItem: string
Try

Acima, temos uma interface StringArray que tem uma assinatura de índice. Essa assinatura de índice afirma que, quando um StringArray é indexado com um number, ele retorna uma string.

Só alguns tipos são permitidos para propriedades de assinatura de índice: string, number, symbol, padrões de template string e uniões formadas apenas por esses tipos.

É possível oferecer suporte a vários tipos de indexadores...

É possível oferecer suporte a vários tipos de indexadores. Repare que, ao usar os indexadores `number` e `string` juntos, o tipo retornado pelo indexador numérico precisa ser um subtipo do tipo retornado pelo indexador de string. Isso acontece porque, ao indexar com um number, o JavaScript converte esse valor para string antes de acessar o objeto. Isso significa que indexar com 100 (um number) é o mesmo que indexar com "100" (uma string), então os dois precisam ser consistentes.

ts
interface Animal {
name: string;
}
 
interface Dog extends Animal {
breed: string;
}
 
// Error: indexing with a numeric string might get you a completely separate type of Animal!
interface NotOkay {
[x: number]: Animal;
'number' index type 'Animal' is not assignable to 'string' index type 'Dog'.2413'number' index type 'Animal' is not assignable to 'string' index type 'Dog'.
[x: string]: Dog;
}
Try

Embora assinaturas de índice de string sejam uma forma poderosa de descrever o padrão de “dicionário”, elas também obrigam que todas as propriedades correspondam ao tipo de retorno. Isso acontece porque uma assinatura de índice de string declara que obj.property também está disponível como obj["property"]. No exemplo a seguir, o tipo de name não corresponde ao tipo da assinatura de índice de string, e o verificador de tipos dá um erro:

ts
interface NumberDictionary {
[index: string]: number;
 
length: number; // ok
name: string;
Property 'name' of type 'string' is not assignable to 'string' index type 'number'.2411Property 'name' of type 'string' is not assignable to 'string' index type 'number'.
}
Try

No entanto, propriedades de tipos diferentes são aceitáveis se a assinatura de índice for uma união dos tipos das propriedades:

ts
interface NumberOrStringDictionary {
[index: string]: number | string;
length: number; // ok, length is a number
name: string; // ok, name is a string
}
Try

Por fim, você pode tornar assinaturas de índice readonly para impedir atribuições aos índices delas:

ts
interface ReadonlyStringArray {
readonly [index: number]: string;
}
 
let myArray: ReadonlyStringArray = getReadOnlyStringArray();
myArray[2] = "Mallory";
Index signature in type 'ReadonlyStringArray' only permits reading.2542Index signature in type 'ReadonlyStringArray' only permits reading.
Try

Você não pode definir myArray[2] porque a assinatura de índice é readonly.

Verificações de propriedades em excesso

Onde e como um objeto recebe um tipo pode fazer diferença no sistema de tipos. Um dos exemplos principais disso é a verificação de propriedades em excesso (excess property checking), que valida o objeto com mais rigor quando ele é criado e atribuído a um tipo de objeto na criação.

ts
interface SquareConfig {
color?: string;
width?: number;
}
 
function createSquare(config: SquareConfig): { color: string; area: number } {
return {
color: config.color || "red",
area: config.width ? config.width * config.width : 20,
};
}
 
let mySquare = createSquare({ colour: "red", width: 100 });
Object literal may only specify known properties, but 'colour' does not exist in type 'SquareConfig'. Did you mean to write 'color'?2561Object literal may only specify known properties, but 'colour' does not exist in type 'SquareConfig'. Did you mean to write 'color'?
Try

Repare que o argumento passado para createSquare está escrito colour em vez de color. Em JavaScript puro, esse tipo de coisa falha silenciosamente.

Dá para argumentar que esse programa está corretamente tipado, já que as propriedades width são compatíveis, não há propriedade color presente, e a propriedade extra colour é irrelevante.

No entanto, o TypeScript assume que provavelmente há um bug nesse código. Literais de objeto recebem um tratamento especial e passam por verificação de propriedades em excesso quando são atribuídos a outras variáveis ou passados como argumentos. Se um literal de objeto tiver alguma propriedade que o “tipo alvo” não tem, você recebe um erro:

ts
let mySquare = createSquare({ colour: "red", width: 100 });
Object literal may only specify known properties, but 'colour' does not exist in type 'SquareConfig'. Did you mean to write 'color'?2561Object literal may only specify known properties, but 'colour' does not exist in type 'SquareConfig'. Did you mean to write 'color'?
Try

Contornar essas verificações é, na verdade, bem simples. O método mais fácil é simplesmente usar uma asserção de tipo:

ts
let mySquare = createSquare({ width: 100, opacity: 0.5 } as SquareConfig);
Try

No entanto, uma abordagem melhor pode ser adicionar uma assinatura de índice de string, se você tiver certeza de que o objeto pode ter algumas propriedades extras usadas de forma especial. Se SquareConfig pode ter as propriedades color e width com os tipos acima, mas também pode ter qualquer número de outras propriedades, podemos defini-la assim:

ts
interface SquareConfig {
color?: string;
width?: number;
[propName: string]: unknown;
}
Try

Aqui estamos dizendo que SquareConfig pode ter qualquer número de propriedades e que, desde que elas não sejam color ou width, os tipos delas não importam.

Mais uma forma de contornar essas verificações, que pode parecer um pouco surpreendente, é atribuir o objeto a outra variável: Como atribuir squareOptions não passa pela verificação de propriedades em excesso, o compilador não vai dar erro:

ts
let squareOptions = { colour: "red", width: 100 };
let mySquare = createSquare(squareOptions);
Try

O contorno acima funciona enquanto existir uma propriedade em comum entre squareOptions e SquareConfig. Neste exemplo, essa propriedade era width. No entanto, ele falha se a variável não tiver nenhuma propriedade de objeto em comum. Por exemplo:

ts
let squareOptions = { colour: "red" };
let mySquare = createSquare(squareOptions);
Type '{ colour: string; }' has no properties in common with type 'SquareConfig'.2559Type '{ colour: string; }' has no properties in common with type 'SquareConfig'.
Try

Tenha em mente que, para um código simples como o acima, você provavelmente não deveria tentar “contornar” essas verificações. Para literais de objeto mais complexos, que têm métodos e guardam estado, talvez seja preciso lembrar dessas técnicas, mas a maioria dos erros de propriedades em excesso são, na verdade, bugs.

Isso significa que, se você estiver tendo problemas com verificações de propriedades em excesso em algo como objetos de opções, talvez precise revisar algumas das suas declarações de tipo. Nesse caso, se for aceitável passar para createSquare um objeto com uma propriedade color ou colour, você deve ajustar a definição de SquareConfig para refletir isso.

Estendendo tipos

É bastante comum ter tipos que são versões mais específicas de outros tipos. Por exemplo, podemos ter um tipo BasicAddress que descreve os campos necessários para enviar cartas e encomendas nos EUA.

ts
interface BasicAddress {
name?: string;
street: string;
city: string;
country: string;
postalCode: string;
}
Try

Em algumas situações, isso é suficiente, mas endereços muitas vezes têm um número de unidade associado quando o prédio do endereço tem várias unidades. Podemos então descrever um AddressWithUnit.

ts
interface AddressWithUnit {
name?: string;
unit: string;
street: string;
city: string;
country: string;
postalCode: string;
}
Try

Isso resolve, mas a desvantagem aqui é que tivemos que repetir todos os outros campos de BasicAddress, quando as mudanças eram puramente aditivas. Em vez disso, podemos estender o tipo original BasicAddress e apenas adicionar os novos campos exclusivos de AddressWithUnit.

ts
interface BasicAddress {
name?: string;
street: string;
city: string;
country: string;
postalCode: string;
}
 
interface AddressWithUnit extends BasicAddress {
unit: string;
}
Try

A palavra-chave extends em uma interface permite copiar, na prática, os membros de outros tipos nomeados e adicionar quaisquer novos membros que quisermos. Isso pode ajudar a reduzir a quantidade de código repetitivo de declaração de tipos que precisamos escrever, e a sinalizar que várias declarações diferentes da mesma propriedade podem estar relacionadas. Por exemplo, AddressWithUnit não precisou repetir a propriedade street e, como street vem de BasicAddress, quem lê sabe que esses dois tipos estão relacionados de alguma forma.

interfaces também podem estender vários tipos.

ts
interface Colorful {
color: string;
}
 
interface Circle {
radius: number;
}
 
interface ColorfulCircle extends Colorful, Circle {}
 
const cc: ColorfulCircle = {
color: "red",
radius: 42,
};
Try

Tipos de interseção

As interfaces nos permitiram construir novos tipos a partir de outros tipos, estendendo-os. O TypeScript oferece outra construção, chamada tipos de interseção, que é usada principalmente para combinar tipos de objeto existentes.

Um tipo de interseção é definido usando o operador &.

ts
interface Colorful {
color: string;
}
interface Circle {
radius: number;
}
 
type ColorfulCircle = Colorful & Circle;
Try

Aqui, combinamos Colorful e Circle por interseção para produzir um novo tipo que tem todos os membros de Colorful e de Circle.

ts
function draw(circle: Colorful & Circle) {
console.log(`Color was ${circle.color}`);
console.log(`Radius was ${circle.radius}`);
}
 
// okay
draw({ color: "blue", radius: 42 });
 
// oops
draw({ color: "red", raidus: 42 });
Object literal may only specify known properties, but 'raidus' does not exist in type 'Colorful & Circle'. Did you mean to write 'radius'?2561Object literal may only specify known properties, but 'raidus' does not exist in type 'Colorful & Circle'. Did you mean to write 'radius'?
Try

Extensão de interface versus interseção

Acabamos de ver duas formas de combinar tipos que são parecidas, mas que têm diferenças sutis. Com interfaces, podemos usar uma cláusula extends para estender outros tipos, e conseguimos fazer algo semelhante com interseções, dando um nome ao resultado com um alias de tipo. A principal diferença entre as duas está em como os conflitos são tratados, e essa diferença costuma ser um dos principais motivos para escolher entre uma interface e um alias de tipo de interseção.

Se interfaces forem definidas com o mesmo nome, o TypeScript vai tentar uni-las se as propriedades forem compatíveis. Se as propriedades não forem compatíveis (ou seja, têm o mesmo nome, mas tipos diferentes), o TypeScript vai gerar um erro.

No caso dos tipos de interseção, propriedades com tipos diferentes são unidas automaticamente. Quando o tipo é usado depois, o TypeScript espera que a propriedade satisfaça os dois tipos ao mesmo tempo, o que pode produzir resultados inesperados.

Por exemplo, o código a seguir vai gerar um erro, porque as propriedades são incompatíveis:

ts
interface Person {
name: string;
}
interface Person {
name: number;
}

Em contraste, o código a seguir compila, mas resulta em um tipo never:

ts
interface Person1 {
name: string;
}
 
interface Person2 {
name: number;
}
 
type Staff = Person1 & Person2
 
declare const staffer: Staff;
staffer.name;
(property) name: never
Try

Neste caso, Staff exigiria que a propriedade name fosse ao mesmo tempo uma string e um number, o que faz com que a propriedade tenha o tipo never.

Tipos de objeto genéricos

Vamos imaginar um tipo Box que pode conter qualquer valor: strings, numbers, Giraffes, o que for.

ts
interface Box {
contents: any;
}
Try

Agora, a propriedade contents está tipada como any, o que funciona, mas pode levar a acidentes mais adiante.

Poderíamos usar unknown, mas isso significaria que, nos casos em que já sabemos o tipo de contents, precisaríamos fazer verificações preventivas ou usar asserções de tipo, que são propensas a erros.

ts
interface Box {
contents: unknown;
}
 
let x: Box = {
contents: "hello world",
};
 
// we could check 'x.contents'
if (typeof x.contents === "string") {
console.log(x.contents.toLowerCase());
}
 
// or we could use a type assertion
console.log((x.contents as string).toLowerCase());
Try

Uma abordagem segura em termos de tipos seria criar tipos Box diferentes para cada tipo de contents.

ts
interface NumberBox {
contents: number;
}
 
interface StringBox {
contents: string;
}
 
interface BooleanBox {
contents: boolean;
}
Try

Mas isso significa que teremos que criar funções diferentes, ou sobrecargas de funções, para operar sobre esses tipos.

ts
function setContents(box: StringBox, newContents: string): void;
function setContents(box: NumberBox, newContents: number): void;
function setContents(box: BooleanBox, newContents: boolean): void;
function setContents(box: { contents: any }, newContents: any) {
box.contents = newContents;
}
Try

Isso é muito código repetitivo. Além disso, podemos precisar, mais tarde, introduzir novos tipos e sobrecargas. É frustrante, já que nossos tipos de caixa e as sobrecargas são, na prática, todos iguais.

Em vez disso, podemos criar um tipo Box genérico, que declara um parâmetro de tipo.

ts
interface Box<Type> {
contents: Type;
}
Try

Você pode ler isso como “Uma Box de Type é algo cujo contents tem o tipo Type”. Mais adiante, quando nos referirmos a Box, precisamos fornecer um argumento de tipo no lugar de Type.

ts
let box: Box<string>;
Try

Pense em Box como um modelo para um tipo real, em que Type é um marcador que será substituído por outro tipo. Quando o TypeScript vê Box<string>, ele substitui todas as ocorrências de Type em Box<Type> por string, e acaba trabalhando com algo como { contents: string }. Em outras palavras, Box<string> e o nosso StringBox de antes funcionam de forma idêntica.

ts
interface Box<Type> {
contents: Type;
}
interface StringBox {
contents: string;
}
 
let boxA: Box<string> = { contents: "hello" };
boxA.contents;
(property) Box<string>.contents: string
 
let boxB: StringBox = { contents: "world" };
boxB.contents;
(property) StringBox.contents: string
Try

Box é reutilizável porque Type pode ser substituído por qualquer coisa. Isso significa que, quando precisamos de uma caixa para um novo tipo, não precisamos declarar um novo tipo Box (embora pudéssemos, se quiséssemos).

ts
interface Box<Type> {
contents: Type;
}
 
interface Apple {
// ....
}
 
// Same as '{ contents: Apple }'.
type AppleBox = Box<Apple>;
Try

Isso também significa que podemos evitar sobrecargas por completo, usando funções genéricas.

ts
function setContents<Type>(box: Box<Type>, newContents: Type) {
box.contents = newContents;
}
Try

Vale notar que aliases de tipo também podem ser genéricos. Poderíamos ter definido nossa nova interface Box<Type>, que era:

ts
interface Box<Type> {
contents: Type;
}
Try

usando um alias de tipo:

ts
type Box<Type> = {
contents: Type;
};
Try

Como aliases de tipo, ao contrário das interfaces, podem descrever mais do que tipos de objeto, também podemos usá-los para escrever outros tipos auxiliares genéricos.

ts
type OrNull<Type> = Type | null;
 
type OneOrMany<Type> = Type | Type[];
 
type OneOrManyOrNull<Type> = OrNull<OneOrMany<Type>>;
type OneOrManyOrNull<Type> = OneOrMany<Type> | null
 
type OneOrManyOrNullStrings = OneOrManyOrNull<string>;
type OneOrManyOrNullStrings = OneOrMany<string> | null
Try

Voltaremos aos aliases de tipo daqui a pouco.

O tipo Array

Tipos de objeto genéricos costumam ser algum tipo de contêiner que funciona independentemente do tipo dos elementos que contém. É ideal que estruturas de dados funcionem assim, para que possam ser reutilizadas com diferentes tipos de dados.

Acontece que temos trabalhado com um tipo assim o tempo todo neste manual: o tipo Array. Sempre que escrevemos tipos como number[] ou string[], isso é, na prática, uma forma abreviada de Array<number> e Array<string>.

ts
function doSomething(value: Array<string>) {
// ...
}
 
let myArray: string[] = ["hello", "world"];
 
// either of these work!
doSomething(myArray);
doSomething(new Array("hello", "world"));
Try

Assim como o tipo Box acima, Array em si é um tipo genérico.

ts
interface Array<Type> {
/**
* Gets or sets the length of the array.
*/
length: number;
 
/**
* Removes the last element from an array and returns it.
*/
pop(): Type | undefined;
 
/**
* Appends new elements to an array, and returns the new length of the array.
*/
push(...items: Type[]): number;
 
// ...
}
Try

O JavaScript moderno também oferece outras estruturas de dados genéricas, como Map<K, V>, Set<T> e Promise<T>. Tudo isso significa que, por causa do comportamento de Map, Set e Promise, elas podem funcionar com qualquer conjunto de tipos.

O tipo ReadonlyArray

ReadonlyArray é um tipo especial que descreve arrays que não devem ser alterados.

ts
function doStuff(values: ReadonlyArray<string>) {
// We can read from 'values'...
const copy = values.slice();
console.log(`The first value is ${values[0]}`);
 
// ...but we can't mutate 'values'.
values.push("hello!");
Property 'push' does not exist on type 'readonly string[]'.2339Property 'push' does not exist on type 'readonly string[]'.
}
Try

Assim como o modificador readonly de propriedades, ele é principalmente uma ferramenta para sinalizar intenção. Quando vemos uma função que retorna ReadonlyArrays, isso nos diz que não devemos alterar o conteúdo de forma alguma; e quando vemos uma função que consome ReadonlyArrays, isso nos diz que podemos passar qualquer array para essa função sem nos preocupar que ela altere o conteúdo.

Diferente de Array, não existe um construtor de ReadonlyArray que possamos usar.

ts
new ReadonlyArray("red", "green", "blue");
'ReadonlyArray' only refers to a type, but is being used as a value here.2693'ReadonlyArray' only refers to a type, but is being used as a value here.
Try

Em vez disso, podemos atribuir Arrays comuns a ReadonlyArrays.

ts
const roArray: ReadonlyArray<string> = ["red", "green", "blue"];
Try

Assim como o TypeScript oferece uma sintaxe abreviada para Array<Type> com Type[], ele também oferece uma sintaxe abreviada para ReadonlyArray<Type> com readonly Type[].

ts
function doStuff(values: readonly string[]) {
// We can read from 'values'...
const copy = values.slice();
console.log(`The first value is ${values[0]}`);
 
// ...but we can't mutate 'values'.
values.push("hello!");
Property 'push' does not exist on type 'readonly string[]'.2339Property 'push' does not exist on type 'readonly string[]'.
}
Try

Uma última observação: diferente do modificador de propriedade readonly, a atribuição não é bidirecional entre Arrays comuns e ReadonlyArrays.

ts
let x: readonly string[] = [];
let y: string[] = [];
 
x = y;
y = x;
The type 'readonly string[]' is 'readonly' and cannot be assigned to the mutable type 'string[]'.4104The type 'readonly string[]' is 'readonly' and cannot be assigned to the mutable type 'string[]'.
Try

Tipos tupla

Um tipo tupla é outro tipo de Array que sabe exatamente quantos elementos contém e exatamente quais tipos ele contém em posições específicas.

ts
type StringNumberPair = [string, number];
Try

Aqui, StringNumberPair é um tipo tupla de string e number. Como ReadonlyArray, ele não tem representação em tempo de execução, mas é significativo para o TypeScript. Para o sistema de tipos, StringNumberPair descreve arrays cujo índice 0 contém uma string e cujo índice 1 contém um number.

ts
function doSomething(pair: [string, number]) {
const a = pair[0];
const a: string
const b = pair[1];
const b: number
// ...
}
 
doSomething(["hello", 42]);
Try

Se tentarmos acessar um índice além do número de elementos, teremos um erro.

ts
function doSomething(pair: [string, number]) {
// ...
 
const c = pair[2];
Tuple type '[string, number]' of length '2' has no element at index '2'.2493Tuple type '[string, number]' of length '2' has no element at index '2'.
}
Try

Também podemos desestruturar tuplas usando a desestruturação de arrays do JavaScript.

ts
function doSomething(stringHash: [string, number]) {
const [inputString, hash] = stringHash;
 
console.log(inputString);
const inputString: string
 
console.log(hash);
const hash: number
}
Try

Tipos tupla são úteis em APIs muito baseadas em convenções, nas quais o significado de cada elemento é “óbvio”. Isso nos dá flexibilidade para dar o nome que quisermos às variáveis na desestruturação. No exemplo acima, pudemos dar aos elementos 0 e 1 o nome que quisemos.

No entanto, como nem todo usuário tem a mesma visão do que é óbvio, pode valer a pena reconsiderar se usar objetos com nomes de propriedade descritivos não seria melhor para a sua API.

Além dessas verificações de tamanho, tipos tupla simples como estes são equivalentes a versões de Arrays que declaram propriedades para índices específicos e declaram length com um tipo literal numérico.

ts
interface StringNumberPair {
// specialized properties
length: 2;
0: string;
1: number;
 
// Other 'Array<string | number>' members...
slice(start?: number, end?: number): Array<string | number>;
}
Try

Outra coisa que pode interessar a você é que tuplas podem ter propriedades opcionais, escrevendo um ponto de interrogação (? depois do tipo do elemento). Elementos opcionais de tupla só podem aparecer no fim, e também afetam o tipo de length.

ts
type Either2dOr3d = [number, number, number?];
 
function setCoordinate(coord: Either2dOr3d) {
const [x, y, z] = coord;
const z: number | undefined
 
console.log(`Provided coordinates had ${coord.length} dimensions`);
(property) length: 2 | 3
}
Try

Tuplas também podem ter elementos rest, que precisam ser de um tipo array/tupla.

ts
type StringNumberBooleans = [string, number, ...boolean[]];
type StringBooleansNumber = [string, ...boolean[], number];
type BooleansStringNumber = [...boolean[], string, number];
Try
  • StringNumberBooleans descreve uma tupla cujos dois primeiros elementos são, respectivamente, string e number, mas que pode ter qualquer número de booleans em seguida.
  • StringBooleansNumber descreve uma tupla cujo primeiro elemento é string, seguido de qualquer número de booleans e terminando com um number.
  • BooleansStringNumber descreve uma tupla cujos elementos iniciais são qualquer número de booleans e que termina com uma string seguida de um number.

Uma tupla com elemento rest não tem um “length” fixo: ela tem apenas um conjunto de elementos conhecidos em posições diferentes.

ts
const a: StringNumberBooleans = ["hello", 1];
const b: StringNumberBooleans = ["beautiful", 2, true];
const c: StringNumberBooleans = ["world", 3, true, false, true, false, true];
Try

Por que elementos opcionais e rest podem ser úteis? Bem, eles permitem que o TypeScript relacione tuplas com listas de parâmetros. Tipos tupla podem ser usados em parâmetros e argumentos rest, então o código a seguir:

ts
function readButtonInput(...args: [string, number, ...boolean[]]) {
const [name, version, ...input] = args;
// ...
}
Try

é basicamente equivalente a:

ts
function readButtonInput(name: string, version: number, ...input: boolean[]) {
// ...
}
Try

Isso é útil quando você quer aceitar um número variável de argumentos com um parâmetro rest, precisa de um número mínimo de elementos, mas não quer introduzir variáveis intermediárias.

Tipos tupla readonly

Uma última observação sobre tipos tupla: eles têm variantes readonly, que podem ser especificadas colocando o modificador readonly na frente, assim como na sintaxe abreviada de arrays.

ts
function doSomething(pair: readonly [string, number]) {
// ...
}
Try

Como você pode imaginar, escrever em qualquer propriedade de uma tupla readonly não é permitido no TypeScript.

ts
function doSomething(pair: readonly [string, number]) {
pair[0] = "hello!";
Cannot assign to '0' because it is a read-only property.2540Cannot assign to '0' because it is a read-only property.
}
Try

Tuplas costumam ser criadas e deixadas sem modificação na maior parte do código, então anotar tipos como tuplas readonly sempre que possível é um bom padrão. Isso também é importante porque literais de array com asserções const são inferidos com tipos tupla readonly.

ts
let point = [3, 4] as const;
 
function distanceFromOrigin([x, y]: [number, number]) {
return Math.sqrt(x ** 2 + y ** 2);
}
 
distanceFromOrigin(point);
Argument of type 'readonly [3, 4]' is not assignable to parameter of type '[number, number]'. The type 'readonly [3, 4]' is 'readonly' and cannot be assigned to the mutable type '[number, number]'.2345Argument of type 'readonly [3, 4]' is not assignable to parameter of type '[number, number]'. The type 'readonly [3, 4]' is 'readonly' and cannot be assigned to the mutable type '[number, number]'.
Try

Aqui, distanceFromOrigin nunca modifica os elementos dele, mas espera uma tupla mutável. Como o tipo de point foi inferido como readonly [3, 4], ele não será compatível com [number, number], já que esse tipo não pode garantir que os elementos de point não serão modificados.

The TypeScript docs are an open source project. Help us improve these pages by sending a Pull Request ❤

Contributors to this page:
DRDaniel Rosenwasser  (52)
OTOrta Therox  (16)
UMDFUlisses, Mago do Flutter  (2)
338elements  (2)
BRBruce Robertson  (2)
24+

Last updated: Nov 16, 2026