3. Os fundamentos
3.1. Os fundamentos do TypeScript
Nota: Daqui em diante, o termo [TypeScript] designará a linguagem tal como definida pela versão 6, um superconjunto tipado do ECMAScript 2026.
Os scripts deste capítulo estão na pasta [basics] do projeto.

3.1.1. Script [basics-01]
Este script usa o exemplo introdutório do curso original de JavaScript, traduzido e tipado em TypeScript:
| /* eslint-disable no-constant-condition */
'use strict';
// isto é um comentário
// constante
const name: string = "dupont";
// uma exibição na tela
console.log("name : ", name);
// um array com elementos de tipos diferentes
// [any] porque este array mistura deliberadamente vários tipos (demonstração)
const array: any[] = ["one", "two", 3, 4];
// seu número de elementos
let n: any = array.length;
// um laço
for (let i = 0; i < n; i++) {
console.log("array[", i, "] = ", array[i]);
}
// inicialização de 2 variáveis com o conteúdo de um array
let [string1, string2]: string[] = ["string1", "string2"];
// concatenação das 2 strings
const string3 = string1 + string2;
// exibe o resultado
console.log([string1, string2, string3]);
// uso de uma função
display(string1);
// o tipo de uma variável pode ser conhecido
displayType("n", n);
displayType("string1", string1);
displayType("array", array);
// o tipo de uma variável pode mudar durante a execução
// [n] é tipada como [any] acima: é justamente isso que permite ao TypeScript
// aceitar essa reatribuição no meio do caminho, como em JavaScript
n = "has changed";
displayType("n", n);
// uma função pode retornar um resultado
let res1: any = f1(4);
console.log("res1=", res1);
// uma função pode retornar um array de valores
let res2: any, res3: any;
[res1, res2, res3] = f2();
console.log("(res1,res2,res3)=", [res1, res2, res3]);
// poderíamos ter recuperado esses valores em um array
let t: any[] = f2();
for (let i = 0; i < t.length; i++) {
console.log("t[", i, "]=", t[i]);
}
// alguns testes
for (let i = 0; i < t.length; i++) {
// exibe apenas as strings
if (typeof (t[i]) === "string") {
console.log("t[", i, "]=", t[i]);
}
}
// operadores de comparação == e ===
if ("2" == (2 as any)) {
console.log("with the == operator, the string 2 is equal to the integer 2");
} else {
console.log("with the == operator, the string 2 is not equal to the integer 2");
}
if (("2" as any) === 2) {
console.log("with the === operator, the string 2 is equal to the integer 2");
} else {
console.log("with the === operator, the string 2 is not equal to the integer 2");
}
// outros testes
for (let i = 0; i < t.length; i++) {
// exibe apenas os inteiros >10
if (typeof (t[i]) === "number" && Math.floor(t[i]) === t[i] && t[i] > 10) {
console.log("t[", i, "]=", t[i]);
}
}
// um laço while
t = [8, 5, 0, -2, 3, 4];
let i = 0;
let sum = 0;
while (i < t.length && t[i] > 0) {
console.log("t[", i, "]=", t[i]);
sum += t[i];
i++;
}
console.log("sum=", sum);
// fim do programa porque não há mais código executável
//exibição
//----------------------------------
function display(str: string): void {
// exibe str
console.log("string=", str);
}
//displayType
//----------------------------------
function displayType(name: string, variable: unknown): void {
// exibe o tipo da variável
console.log("type[variable ", name, "]=", typeof (variable));
}
//----------------------------------
function f1(param: number): number {
// soma 10 a param
return param + 10;
}
//----------------------------------
function f2(): any[] {
// retorna 3 valores
return ["one", 0, 100];
}
|
Vamos comentar este código:
- linha 5: [const name: string = "dupont"] — em TypeScript, é possível anotar explicitamente o tipo de uma variável acrescentando
type após o seu nome. Aqui, name tem a garantia de ser uma string durante todo o programa;
- linha 10: [const array: any[] = ...] — este array mistura intencionalmente strings e números. O tipo
any[] diz ao TypeScript para não verificar os tipos dos elementos: é uma escolha explícita, distinta da omissão de tipagem (que o modo strict proíbe);
- linha 12: [let n: any = array.length] —
n é tipada como any porque, mais adiante (linha 32), recebe uma string depois de ter recebido um número. Em JavaScript, uma variável pode mudar de tipo livremente; em TypeScript, isso só é permitido se for explicitamente autorizado com any (ou uma união de tipos, como number | string);
- linha 54: ["2" == (2 as any)] — o TypeScript proíbe, por padrão, comparar dois valores de tipos incompatíveis (string e número) com
==. A expressão (2 as any) é uma asserção de tipo: dizemos explicitamente ao TypeScript “trate este valor como any; não verifique seu tipo aqui”, o que ilustra deliberadamente a coerção de tipos própria do operador ==;
- linha 93: a função [function displayType(name: string, variable: unknown): void] tipa seu segundo parâmetro como
unknown em vez de any. Ao contrário de any, unknown proíbe usar o valor sem antes verificá-lo—aqui, usamos simplesmente typeof(variable), o que é permitido mesmo com unknown;
- linhas 86–108: as funções agora têm um tipo de retorno explícito (: number, : void..., etc.), escrito após a lista de parâmetros.
Vamos executar este script:
npx tsx basics/basics-01.ts
Resultado da execução:
| name : dupont
array[ 0 ] = one
array[ 1 ] = two
array[ 2 ] = 3
array[ 3 ] = 4
[ 'string1', 'string2', 'string1string2' ]
string= string1
type[variable n ]= number
type[variable string1 ]= string
type[variable array ]= object
type[variable n ]= string
res1= 14
(res1,res2,res3)= [ 'one', 0, 100 ]
t[ 0 ]= one
t[ 1 ]= 0
t[ 2 ]= 100
t[ 0 ]= one
with the == operator, the string 2 is equal to the integer 2
with the === operator, the string 2 is not equal to the integer 2
t[ 2 ]= 100
t[ 0 ]= 8
t[ 1 ]= 5
sum= 13
|
3.1.2. Script [basics-02]
O script [basics-02] demonstra o uso das palavras-chave [let] e [const]:
| 'use strict';
// para inicializar uma variável, usamos let ou const
// let para variáveis
let x: number = 4;
x++;
console.log(x);
// const para constantes
const y: number = 10;
x += y;
// proibido
y++;
|
- [let] declara uma variável cujo valor pode mudar (linhas 4–5);
- [const] declara uma constante cujo valor não pode mudar (linha 8);
- linha 11: tenta-se reatribuir a constante y com y++. É aqui que o TypeScript oferece uma vantagem real sobre o JavaScript.
Mesmo antes de executar o script, a verificação de tipos sinaliza o erro:
Resultado da execução:
| basics/basics-02.ts(11,1): error TS2588: Cannot assign to 'y' because it is a constant.
|
No JavaScript original, esse mesmo erro só seria detectado em tempo de execução. Vamos executar este script mesmo assim com tsx (que executa o código sem fazer antes a verificação de tipos, ao contrário do tsc) para ver o erro como o JavaScript realmente o lança:
npx tsx basics/basics-02.ts
Resultado da execução:
| 5
TypeError: Assignment to constant variable.
at basics/basics-02.ts:11:1
|
Importante: tsx transpila o TypeScript em JavaScript sem verificação de tipos (como faz o Babel), para uma execução rápida durante o desenvolvimento. É por isso que este script é executado (e falha durante a execução) mesmo não compilando com o tsc. Para ser avisado do erro antes da execução, use o VSCode (que executa o tsc em segundo plano) ou o comando `npm run check` .
3.1.3. Script [basics-03]
Ilustra o escopo das variáveis globais, que são visíveis dentro de uma função:
| 'use strict';
// escopo das variáveis
let count: number = 1;
function doSomething(): void {
// count é conhecida aqui
console.log("count=", count);
}
// chamada
doSomething();
|
npx tsx basics/basics-03.ts
Resultado da execução:
3.1.4. Script [basics-04]
Uma variável local dentro de uma função oculta (mascara) uma variável global de mesmo nome:
| 'use strict';
// escopo das variáveis
const count: number = 1;
function doSomething(): void {
// a variável local oculta a variável global
const count = 2;
console.log("count inside function=", count);
}
// variável global
console.log("count outside function=", count);
// variável local
doSomething();
|
npx tsx basics/basics-04.ts
Resultado da execução:
| count outside function= 1
count inside function= 2
|
3.1.5. Script [basics-05]
Uma variável local (const count dentro da função) não é visível fora dessa função:
| 'use strict';
// escopo das variáveis
function doSomething(): void {
// variável local da função
const count = 2;
console.log("count inside function=", count);
}
// aqui count não é conhecida
console.log("count outside function=", count);
doSomething();
|
Aqui também, o TypeScript detecta o problema durante a compilação—não é preciso executar o script para descobri-lo:
Resultado da execução:
| basics/basics-05.ts(9,40): error TS2304: Cannot find name 'count'.
|
E quando executado com tsx:
npx tsx basics/basics-05.ts
Resultado da execução:
| ReferenceError: count is not defined
at basics/basics-05.ts:9:40
|
3.1.6. Script [basics-06]
Este script compara o escopo de bloco ([let], [const]) com a ausência de escopo de bloco ([var]):
| 'use strict';
// a palavra-chave [let] define uma variável com escopo de bloco
{
// a variável [count] só é conhecida neste bloco
let count: number = 1;
console.log("count=", count);
}
// aqui a variável [count] não é conhecida
count++;
// a palavra-chave [const] define uma variável com escopo de bloco
{
// a variável [count2] só é conhecida neste bloco
const count2: number = 1;
console.log("count=", count2);
}
// aqui a variável [count2] não é conhecida
count2++;
// a palavra-chave [var] não define uma variável com escopo de bloco
{
// a variável [count3] será conhecida globalmente
var count3: number = 1;
console.log("count=", count3);
}
// aqui a variável [count3] é conhecida
count3++;
|
- Uma variável declarada com [let] ou [const] dentro de um bloco { } existe apenas nesse bloco;
- uma variável declarada com [var] ignora os blocos: permanece visível em toda a função (ou script) que a contém—esse era o único comportamento disponível antes do ECMAScript de 2015, fonte de muitos bugs, daí a recomendação de preferir sempre [let]/[const].
Compilação:
Resultado da execução:
| basics/basics-06.ts(9,1): error TS2552: Cannot find name 'count'. Did you mean 'count3'?
basics/basics-06.ts(18,1): error TS2552: Cannot find name 'count2'. Did you mean 'count3'?
|
Execução (o script para no primeiro erro encontrado, em count):
npx tsx basics/basics-06.ts
Resultado da execução:
| count= 1
ReferenceError: count is not defined
at basics/basics-06.ts:9:1
|
3.1.7. Script [basics-07]
Visão geral dos principais tipos do TypeScript:
| 'use strict';
// tipos de dados do JS
const var1: number = 10;
const var2: string = "abc";
const var3: boolean = true;
const var4: number[] = [1, 2, 3];
const var5: { name: string } = {
name: 'axèle'
};
const var6: () => number = function () {
return +3;
}
// exibição dos tipos
console.log("typeof(var1)=", typeof (var1));
console.log("typeof(var2)=", typeof (var2));
console.log("typeof(var3)=", typeof (var3));
console.log("typeof(var4)=", typeof (var4));
console.log("typeof(var5)=", typeof (var5));
console.log("typeof(var6)=", typeof (var6));
|
- [var5: { name: string }] — um tipo de objeto inline: a forma esperada do objeto é descrita diretamente entre chaves, sem precisar declarar uma interface separada;
- [var6: () => number] — um tipo de função: uma função sem parâmetros que retorna um número;
- em tempo de execução,
typeof continua sendo o do JavaScript (ele ignora as anotações de tipo, que existem apenas em tempo de compilação e desaparecem depois): é por isso que typeof(var4) (um array) e typeof(var5) (um objeto) retornam ambos "object".
npx tsx basics/basics-07.ts
Resultado da execução:
| typeof(var1)= number
typeof(var2)= string
typeof(var3)= boolean
typeof(var4)= object
typeof(var5)= object
typeof(var6)= function
|
3.1.8. Script [basics-08]
As conversões de tipo, implícitas e explícitas, permanecem como no JavaScript (o TypeScript não altera a execução):
| 'use strict';
// mudanças implícitas de tipo
// tipo -> bool
console.log("---------------[Implicit conversion to a boolean]------------------------------");
showBool("abcd");
showBool("");
showBool([1, 2, 3]);
showBool([]);
showBool(null);
showBool(0.0);
showBool(0);
showBool(4.6);
showBool({});
showBool(undefined);
// [any] porque esta função aceita deliberadamente qualquer tipo como entrada
function showBool(data: any): void {
// a conversão do dado para booleano é feita automaticamente no teste a seguir
console.log("[data=", data, "], [type(data)]=", typeof (data), "[boolean value(data)]=", data ? true : false);
}
// mudanças implícitas de tipo para um tipo numérico
console.log("---------------[Implicit conversion to a number]------------------------------");
showNumber("12");
showNumber("45.67");
showNumber("abcd");
function showNumber(data: any): void {
// data + 1 não funciona porque o JS faz então uma concatenação de strings em vez de uma soma
const number = data * 1;
console.log("[data=", data, "], [type(data)]=", typeof (data), "[number]=", number, "[type(number)]=", typeof (number));
}
// mudanças explícitas de tipo para booleano
console.log("---------------[Explicit conversion to a boolean]------------------------------");
showBool2("abcd");
showBool2("");
showBool2([1, 2, 3]);
showBool2([]);
showBool2(null);
showBool2(0.0);
showBool2(0);
showBool2(4.6);
showBool2({});
showBool2(undefined);
function showBool2(data: any): void {
// a conversão do dado para booleano é feita explicitamente no teste a seguir
console.log("[", data, "], [type(data)]=", typeof (data), "[boolean value(data)]=", Boolean(data));
}
// mudanças explícitas de tipo para Number
console.log("---------------[Explicit conversion to a number]------------------------------");
showNumber2("12.45");
showNumber2(67.8);
showNumber2(true);
showNumber2(null);
function showNumber2(data: any): void {
const number = Number(data);
console.log("[data=", data, "], [type(data)]=", typeof (data), "[number]=", number, "[type(number)]=", typeof (number));
}
// para String
console.log("---------------[Explicit conversion to a string]------------------------------");
showString(5);
showString(6.7);
showString(false);
showString(null);
function showString(data: any): void {
const str = String(data);
console.log("[data=", data, "], [type(data)]=", typeof (data), "[string]=", str, "[type(string)]=", typeof (str));
}
// algumas conversões implícitas inesperadas
console.log("---------------[Other cases]------------------------------");
const string1: string = '1000.78';
// concatenação de strings por padrão
const data1 = string1 + 1.034;
console.log("data1=", data1, "type=", typeof (data1));
const data2 = 1.034 + string1;
console.log("data2=", data2, "type=", typeof (data2));
// conversão explícita para número
const data3 = Number(string1) + 1.034;
console.log("data3=", data3, "type=", typeof (data3));
// true é convertido no número 1
const data4 = (true as any) * 1.18;
console.log("data4=", data4, "type=", typeof (data4));
// false é convertido no número 0
const data5 = (false as any) * 1.18;
console.log("data5=", data5, "type=", typeof (data5));
|
- Todas as funções deste script declaram seu parâmetro
data como any: isso é intencional, pois o objetivo é justamente mostrar como a mesma função se comporta com valores de tipos muito diferentes (string, array, null, undefinedetc.);
- [Boolean(data)], [Number(data)] e [String(data)] são conversões explícitas—sempre preferíveis às conversões implícitas, por serem mais previsíveis e mais legíveis;
- último bloco:
string1 + 1.034 resulta em concatenação de strings (o operador + com uma string em qualquer dos lados dá prioridade à concatenação), ao passo que Number(string1) + 1.034 resulta em adição numérica.
npx tsx basics/basics-08.ts
Resultado da execução:
| ---------------[Implicit conversion to a boolean]------------------------------
[data= abcd ], [type(data)]= string [boolean value(data)]= true
[data= ], [type(data)]= string [boolean value(data)]= false
[data= [ 1, 2, 3 ] ], [type(data)]= object [boolean value(data)]= true
[data= [] ], [type(data)]= object [boolean value(data)]= true
[data= null ], [type(data)]= object [boolean value(data)]= false
[data= 0 ], [type(data)]= number [boolean value(data)]= false
[data= 0 ], [type(data)]= number [boolean value(data)]= false
[data= 4.6 ], [type(data)]= number [boolean value(data)]= true
[data= {} ], [type(data)]= object [boolean value(data)]= true
[data= undefined ], [type(data)]= undefined [boolean value(data)]= false
---------------[Implicit conversion to a number]------------------------------
[data= 12 ], [type(data)]= string [number]= 12 [type(number)]= number
[data= 45.67 ], [type(data)]= string [number]= 45.67 [type(number)]= number
[data= abcd ], [type(data)]= string [number]= NaN [type(number)]= number
---------------[Explicit conversion to a boolean]------------------------------
[ abcd ], [type(data)]= string [boolean value(data)]= true
[ ], [type(data)]= string [boolean value(data)]= false
[ [ 1, 2, 3 ] ], [type(data)]= object [boolean value(data)]= true
[ [] ], [type(data)]= object [boolean value(data)]= true
[ null ], [type(data)]= object [boolean value(data)]= false
[ 0 ], [type(data)]= number [boolean value(data)]= false
[ 0 ], [type(data)]= number [boolean value(data)]= false
[ 4.6 ], [type(data)]= number [boolean value(data)]= true
[ {} ], [type(data)]= object [boolean value(data)]= true
[ undefined ], [type(data)]= undefined [boolean value(data)]= false
---------------[Explicit conversion to a number]------------------------------
[data= 12.45 ], [type(data)]= string [number]= 12.45 [type(number)]= number
[data= 67.8 ], [type(data)]= number [number]= 67.8 [type(number)]= number
[data= true ], [type(data)]= boolean [number]= 1 [type(number)]= number
[data= null ], [type(data)]= object [number]= 0 [type(number)]= number
---------------[Explicit conversion to a string]------------------------------
[data= 5 ], [type(data)]= number [string]= 5 [type(string)]= string
[data= 6.7 ], [type(data)]= number [string]= 6.7 [type(string)]= string
[data= false ], [type(data)]= boolean [string]= false [type(string)]= string
[data= null ], [type(data)]= object [string]= null [type(string)]= string
---------------[Other cases]------------------------------
data1= 1000.781.034 type= string
data2= 1.0341000.78 type= string
data3= 1001.814 type= number
data4= 1.18 type= number
data5= 0 type= number
|
3.1.9. Script [basics-09]
[NOVO desde 2019] Este script apresenta operadores introduzidos no ECMAScript 2020–2021, hoje muito usados:
| 'use strict';
// ========================================================================
// [NOVO desde 2019] alguns operadores modernos muito usados no dia a dia
// ========================================================================
// ------------------------------------------------------------------------
// 1) o operador de coalescência nula [??] (ECMAScript 2020)
// ------------------------------------------------------------------------
// com [||], um valor "falsy" (0, "", false, NaN, ...) aciona o valor padrão,
// o que nem sempre é o que queremos
const quantity1: number = 0;
console.log("with || : quantity1 || 10 =", quantity1 || 10); // -> 10 (bug! 0 é, no entanto, uma quantidade válida)
// [??] aciona o valor padrão somente se o valor for null ou undefined
console.log("with ?? : quantity1 ?? 10 =", quantity1 ?? 10); // -> 0 (correto)
const quantity2: number | null = null;
console.log("quantity2 ?? 10 =", quantity2 ?? 10); // -> 10 (quantity2 é null)
const quantity3: number | undefined = undefined;
console.log("quantity3 ?? 10 =", quantity3 ?? 10); // -> 10 (quantity3 é undefined)
// ------------------------------------------------------------------------
// 2) encadeamento opcional [?.] (ECMAScript 2020)
// ------------------------------------------------------------------------
// antes de 2020, para acessar com segurança uma propriedade profunda, era preciso
// testar cada nível: if (person && person.address && person.address.city) ...
// interface comum: [address] é opcional (person2 não tem endereço)
interface PersonWithOptionalAddress {
name: string;
address?: { city: string };
}
const person1: PersonWithOptionalAddress = {
name: "Dupont",
address: {
city: "Nantes"
}
};
const person2: PersonWithOptionalAddress = {
name: "Martin"
// sem endereço!
};
// [?.] interrompe a avaliação e retorna [undefined] assim que uma etapa é null ou undefined
// em vez de lançar um erro "Cannot read properties of undefined"
console.log("person1 city =", person1.address?.city);
console.log("person2 city =", person2.address?.city); // -> undefined, sem erro
// podemos combinar [?.] e [??] para fornecer um valor de fallback
console.log("person2 city (with default) =", person2.address?.city ?? "unknown city");
// [?.] também funciona em chamadas de método...
interface ObjectWithMethod {
sayHello(): string;
sayGoodbye?(): string;
}
const objectWithMethod: ObjectWithMethod = {
sayHello() {
return "hello!";
}
};
console.log("existing method call :", objectWithMethod.sayHello?.());
console.log("missing method call :", objectWithMethod.sayGoodbye?.()); // -> undefined, sem erro
// ...e no acesso a um elemento de array
const arrayOrNull: number[] | null = null;
console.log("element of a missing array :", arrayOrNull?.[0]); // -> undefined
// ------------------------------------------------------------------------
// 3) os operadores de atribuição lógica [||=], [&&=], [??=] (ECMAScript 2021)
// ------------------------------------------------------------------------
// esses operadores combinam um teste lógico e uma atribuição em uma única expressão
// [a ??= b] equivale a [a = a ?? b]: atribui b somente se a for null/undefined
interface Configuration {
delay: number;
page?: number;
}
const config: Configuration = { delay: 0, page: undefined };
config.delay ??= 1000; // delay já vale 0 (valor válido) -> permanece inalterado
config.page ??= 1; // page é undefined -> passa a valer 1
console.log("config after ??= :", config);
// [a ||= b] equivale a [a = a || b]: atribui b se a for "falsy" (0, "", null, undefined, false...)
let displayedMessage: string = "";
displayedMessage ||= "default message";
console.log("displayedMessage after ||= :", displayedMessage);
// [a &&= b] equivale a [a = a && b]: atribui b somente se a já for "truthy"
interface LoggedInUser {
name: string;
loggedIn?: boolean;
}
let loggedInUser: LoggedInUser | null = { name: "Ana" };
loggedInUser &&= { ...loggedInUser, loggedIn: true };
console.log("loggedInUser after &&= :", loggedInUser);
// ------------------------------------------------------------------------
// 4) separadores numéricos [_] (ECMAScript 2021)
// ------------------------------------------------------------------------
// puramente visual: torna os números grandes mais legíveis no código-fonte
const oneMillion: number = 1_000_000;
const bankCard: bigint = 1234_5678_9012_3456n; // aqui combinado com um BigInt (veja abaixo)
console.log("oneMillion =", oneMillion);
console.log("bankCard =", bankCard);
// ------------------------------------------------------------------------
// 5) o tipo [BigInt] (ECMAScript 2020)
// ------------------------------------------------------------------------
// o tipo [number] do JavaScript perde a precisão a partir de cerca de 2^53
console.log("Number.MAX_SAFE_INTEGER =", Number.MAX_SAFE_INTEGER);
console.log("Number.MAX_SAFE_INTEGER + 1 =", Number.MAX_SAFE_INTEGER + 1);
console.log("Number.MAX_SAFE_INTEGER + 2 =", Number.MAX_SAFE_INTEGER + 2); // -> mesmo resultado que +1, impreciso!
// um [BigInt] é escrito com um [n] no final, ou criado com BigInt(...)
const bigNumber1: bigint = 9007199254740993n;
const bigNumber2: bigint = BigInt("9007199254740993");
console.log("bigNumber1 =", bigNumber1, ", type =", typeof (bigNumber1));
console.log("bigNumber1 === bigNumber2 :", bigNumber1 === bigNumber2);
// um BigInt e um number não podem ser misturados diretamente em um cálculo
try {
console.log((bigNumber1 as any) + 1); // provoca um erro [TypeError]
} catch (error: any) {
console.log("expected error :", error.message);
}
// é necessária uma conversão explícita
console.log("bigNumber1 + 1n =", bigNumber1 + 1n);
|
Vamos discutir as novidades mais importantes:
- [??], coalescência nula (ECMAScript 2020): ao contrário de [||], que retorna seu valor padrão para qualquer valor “falso” (0, "", false...), [??] só é acionado se o valor for null ou undefined. É a escolha certa para uma quantidade que pode legitimamente ser 0;
- [?.], encadeamento opcional (ECMAScript 2020): interrompe a avaliação e retorna
undefined assim que uma etapa intermediária for null ou undefined, em vez de lançar um erro. Também funciona em chamadas de método (object.method?.()) e na indexação (array?.[0]);
- [||=], [&&=], [??=], operadores de atribuição lógica (ECMAScript 2021): combinam um teste lógico e uma atribuição em uma única expressão (a ??= b equivale a a = a ?? b);
- os separadores numéricos 1_000_000 (ECMAScript 2021): puramente visuais, tornam os números grandes mais legíveis no código-fonte;
- o tipo [BigInt] (ECMAScript 2020), indicado por um “n” final (9007199254740993n): ao contrário de
number, não perde precisão além de Number.MAX\_SAFE\_INTEGER. Um BigInt e um number não podem ser misturados diretamente em um cálculo, como mostra o bloco try/catch do script.
npx tsx basics/basics-09.ts
Resultado da execução:
| with || : quantity1 || 10 = 10
with ?? : quantity1 ?? 10 = 0
quantity2 ?? 10 = 10
quantity3 ?? 10 = 10
person1 city = Nantes
person2 city = undefined
person2 city (with default) = unknown city
existing method call : hello!
missing method call : undefined
element of a missing array : undefined
config after ??= : { delay: 0, page: 1 }
displayedMessage after ||= : default message
loggedInUser after &&= : { name: 'Ana', loggedIn: true }
oneMillion = 1000000
bankCard = 1234567890123456n
Number.MAX_SAFE_INTEGER = 9007199254740991
Number.MAX_SAFE_INTEGER + 1 = 9007199254740992
Number.MAX_SAFE_INTEGER + 2 = 9007199254740992
bigNumber1 = 9007199254740993n , type = bigint
bigNumber1 === bigNumber2 : true
expected error : Cannot mix BigInt and other types, use explicit conversions
bigNumber1 + 1n = 9007199254740994n
|
3.1.10. Conclusão
Vimos os fundamentos do sistema de tipos do TypeScript: anotações de tipo em variáveis, parâmetros de funções e valores de retorno; os tipos any e unknown ; os principais operadores modernos da linguagem (??, ?., ||=/&&=/??=); e o tipo BigInt . O próximo capítulo trata dos arrays.
3.2. Arrays
Os scripts deste capítulo estão na pasta [arrays] do projeto:

3.2.1. Script [arr-01]
O script a seguir ilustra uma característica essencial dos arrays do TypeScript/JavaScript: eles são objetos manipulados por referência (por meio de um ponteiro), e não dados copiados a cada atribuição.
| 'use strict';
// um array é um objeto manipulado por meio de seu endereço
const arr1: number[] = [1, 2, 3];
// cópia de endereços
const arr2: number[] = arr1;
// arr1 e arr2 apontam para o mesmo array
console.log("arr1===arr2 :", arr1 === arr2);
// o array pode ser modificado tanto por arr1 quanto por arr2
arr2[1] = 10;
console.log("arr1=", arr1);
console.log("arr2=", arr2);
|
Resultado da execução:
| arr1===arr2 : true
arr1= [ 1, 10, 3 ]
arr2= [ 1, 10, 3 ]
|
- arr1===arr2 resulta em true: as duas variáveis apontam para o mesmo array na memória;
- portanto, modificar o array por meio de
arr2 também modifica o que se vê por meio de arr1—isso é consequência direta de arr1 e arr2 se referirem aos mesmos dados.
3.2.2. Script [arr-02]
Este script mostra que o array do TypeScript não tem tamanho fixo e se comporta mais como uma lista indexada dinâmica do que como um array de uma linguagem compilada tradicional:
| 'use strict';
// array
// [any] porque este array conterá lacunas e valores de tipos diferentes
const arr: any[] = [];
console.log("arr=", arr, ", length=[", arr.length, "]");
console.log("-------------------------------");
// inicialização de um elemento
arr[3] = 100;
arr[1] = "eight";
// array
console.log("arr=", arr, ", length=[", arr.length, "]");
console.log("-------------------------------");
// toString
console.log("arr.toString=[", arr.toString(), "]");
console.log("-------------------------------");
// as chaves do array são seus índices
for (let key of arr.keys()) {
console.log("key=[", key, "], value=[", arr[key], "]");
}
console.log("-------------------------------");
// os valores do array
for (let value of arr.values()) {
console.log("value=[", value, "]");
}
|
- linha 5: const arr: any[] = [] — um array vazio, tipado como
any[] porque conterá intencionalmente “lacunas”;
- linhas 9–10: o elemento nº 3 pode ser inicializado mesmo que os elementos 0, 1 e 2 ainda não existam—eles se tornam “lacunas” (empty items), que são distintas de
undefined embora muitas vezes sejam exibidas de forma parecida;
- linhas 18–20: os métodos keys() e values() retornam iteradores que podem ser percorridos com for...of.
Resultado da execução:
| arr= [] , length=[ 0 ]
-------------------------------
arr= [ <1 empty item>, 'eight', <1 empty item>, 100 ] , length=[ 4 ]
-------------------------------
arr.toString=[ ,eight,,100 ]
-------------------------------
key=[ 0 ], value=[ undefined ]
key=[ 1 ], value=[ eight ]
key=[ 2 ], value=[ undefined ]
key=[ 3 ], value=[ 100 ]
-------------------------------
value=[ undefined ]
value=[ eight ]
value=[ undefined ]
value=[ 100 ]
|
3.2.3. Script [arr-03]
Este script demonstra os principais métodos para manipular um array: percorrer, adicionar e remover elementos.
| 'use strict';
// um array pode conter dados de tipos diferentes
// [any] porque este array mistura deliberadamente vários tipos (demonstração)
const arr: any[] = [1, 2, "one", "two", true, [10, 20], { prop1: 10, prop2: "abc" }];
// console.log pode exibir o conteúdo de um array
show(1);
console.log("arr=", arr);
show(2);
// percurso do array com foreach
arr.forEach(element => {
console.log("element=", element, typeof (element));
});
show("2b");
// outra sintaxe para fazer a mesma coisa
arr.forEach(function (element) {
console.log("element=", element, typeof (element));
});
show(3);
// percurso do array com for
for (let i = 0; i < arr.length; i++) {
console.log("i=", i, "arr[i]=", arr[i]);
}
show(4);
// modificação de arr[i]
arr[5] = [];
// exibição
console.log("arr=", arr);
show(5);
// removemos o último elemento do array
let element = arr.pop();
console.log("element=", element, "arr=", arr);
show(6);
// adicionamos um elemento no final do array
arr.push('xyz');
console.log("arr=", arr);
show(7);
// adicionamos um elemento no início do array
arr.unshift(1000);
console.log("arr=", arr);
show(8);
// removemos o 1º elemento
element = arr.shift();
console.log("element=", element, "arr=", arr);
show(9);
// removemos o elemento nº 2 do array
element = arr.splice(2, 1);
console.log("element=", element, "arr=", arr);
show(10);
// removemos dois elementos do array a partir do elemento nº 1
element = arr.splice(1, 2);
console.log("element=", element, "arr=", arr);
// função
function show(param: number | string): void {
console.log("[", param, ":::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ]");
}
|
- Linha 4: embora
arr seja declarado como const, seu conteúdo pode ser modificado (linha 25, arr[5] = []). O que é constante é o ponteiro para o array, não o array em si;
- linhas 10–12:
forEach percorre o array e chama a função passada como parâmetro para cada elemento—aqui escrita com a notação de seta: element => { ... };
- linhas 15–17: o mesmo, escrito com a sintaxe tradicional de function—as duas formas são equivalentes;
- Os métodos pop(), push(), unshift(), shift() e splice() modificam o array no próprio lugar (têm efeitos colaterais): essa é uma diferença importante em relação aos métodos “imutáveis” vistos no script arr-05.
Resultado da execução (formatado em uma única linha para facilitar a leitura):
| [ 1 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ]
arr= [ 1, 2, 'one', 'two', true, [ 10, 20 ], { prop1: 10, prop2: 'abc' } ]
[ 2 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ]
element= 1 number
element= 2 number
element= one string
element= two string
element= true boolean
element= [ 10, 20 ] object
element= { prop1: 10, prop2: 'abc' } object
[ 2b :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ]
element= 1 number
element= 2 number
element= one string
element= two string
element= true boolean
element= [ 10, 20 ] object
element= { prop1: 10, prop2: 'abc' } object
[ 3 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ]
i= 0 arr[i]= 1
i= 1 arr[i]= 2
i= 2 arr[i]= one
i= 3 arr[i]= two
i= 4 arr[i]= true
i= 5 arr[i]= [ 10, 20 ]
i= 6 arr[i]= { prop1: 10, prop2: 'abc' }
[ 4 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ]
arr= [ 1, 2, 'one', 'two', true, [], { prop1: 10, prop2: 'abc' } ]
[ 5 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ]
element= { prop1: 10, prop2: 'abc' } arr= [ 1, 2, 'one', 'two', true, [] ]
[ 6 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ]
arr= [ 1, 2, 'one', 'two', true, [], 'xyz' ]
[ 7 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ]
arr= [ 1000, 1, 2, 'one', 'two', true, [], 'xyz' ]
[ 8 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ]
element= 1000 arr= [ 1, 2, 'one', 'two', true, [], 'xyz' ]
[ 9 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ]
element= [ 'one' ] arr= [ 1, 2, 'two', true, [], 'xyz' ]
[ 10 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ]
element= [ 2, 'two' ] arr= [ 1, true, [], 'xyz' ]
|
3.2.4. Script [arr-04]
Este script apresenta os métodos funcionais de transformação de um array: map, reduce, filter, find, findIndex, indexOf, sort.
| 'use strict';
// métodos de manipulação de arrays
// um array
const arr: number[] = [];
for (let i = 0; i < 10; i++) {
arr[i] = i * 10;
}
// exibição
console.log("arr=", arr);
// map
const arr2 = arr.map(element => {
return { prop1: element, prop2: element * element }
});
// exibição
console.log("arr=", arr);
console.log("arr2=", arr2);
// reduce sem valor inicial
const sum = arr.reduce((accumulator, currentValue) => accumulator + currentValue);
console.log("sum arr=", sum);
// reduce com valor inicial 10
const sum2 = arr.reduce((accumulator, currentValue) => accumulator + currentValue, 10);
console.log("sum2 arr=", sum2);
// filter
const arr4 = arr.filter((element) => {
return element > 50;
});
console.log("arr4=", arr4);
// find
const element1 = arr.find((element) => (element > 20));
console.log("element1=", element1);
// findIndex
const index1 = arr.findIndex((element) => (element === 20));
console.log("index1 20=", index1);
// indexOf
const index2 = arr.indexOf(30);
console.log("index2 30=", index2);
const index3 = arr.indexOf(31);
console.log("index3 31=", index3);
// lastIndexOf
const index4 = [4, 5, 4, 2].lastIndexOf(4);
console.log("index4 4=", index4);
// sort
const arr5 = [4, 5, 4, 2].sort();
console.log("arr5=", arr5);
// sort reverso
const arr6 = [4, 5, 4, 2].sort((e1, e2) => {
if (e1 > e2) {
return -1;
}
else if (e1 === e2) {
return 0;
} else {
return +1;
}
});
console.log("arr6=", arr6);
|
- [map] transforma cada elemento e retorna um novo array—o original permanece inalterado;
- [reduce] “acumula” os elementos, um a um, em um único resultado. O primeiro parâmetro de sua função (accumulator) é o resultado acumulado até o momento; o segundo (currentValue) é o elemento atual. Sem valor inicial (linha 20), o acumulador começa com o primeiro elemento do array;
- [filter] mantém apenas os elementos para os quais a função retorna um valor “verdadeiro”;
- [find] retorna o primeiro elemento que satisfaz o critério (ou
undefined), enquanto [findIndex] retorna seu índice (ou -1);
- [sort] sem parâmetros ordena na ordem natural. Com uma função de comparação (e1, e2) => ..., você tem controle total sobre a ordem: -1 se e1 deve vir antes de e2, +1 caso contrário e 0 em caso de empate.
Resultado da execução:
| arr= [ 0, 10, 20, 30, 40, 50, 60, 70, 80, 90 ]
arr= [ 0, 10, 20, 30, 40, 50, 60, 70, 80, 90 ]
arr2= [
{ prop1: 0, prop2: 0 },
{ prop1: 10, prop2: 100 },
{ prop1: 20, prop2: 400 },
{ prop1: 30, prop2: 900 },
{ prop1: 40, prop2: 1600 },
{ prop1: 50, prop2: 2500 },
{ prop1: 60, prop2: 3600 },
{ prop1: 70, prop2: 4900 },
{ prop1: 80, prop2: 6400 },
{ prop1: 90, prop2: 8100 }
]
sum arr= 450
sum2 arr= 460
arr4= [ 60, 70, 80, 90 ]
element1= 30
index1 20= 2
index2 30= 3
index3 31= -1
index4 4= 2
arr5= [ 2, 4, 4, 5 ]
arr6= [ 5, 4, 4, 2 ]
|
3.2.5. Script [arr-05]
[NOVO desde 2019] Este script demonstra os novos métodos de array introduzidos entre 2022 e 2023:
| 'use strict';
// ========================================================================
// [NOVO desde 2019] novos métodos de array
// ========================================================================
// ------------------------------------------------------------------------
// 1) at(index) (ECMAScript 2022)
// ------------------------------------------------------------------------
// antes, para acessar o último elemento de um array, escrevíamos arr[arr.length - 1]
const arr: number[] = [10, 20, 30, 40, 50];
console.log("arr[arr.length - 1] =", arr[arr.length - 1]); // forma antiga
console.log("arr.at(-1) =", arr.at(-1)); // -> último elemento, mais legível
console.log("arr.at(-2) =", arr.at(-2)); // -> penúltimo elemento
console.log("arr.at(0) =", arr.at(0)); // -> equivale a arr[0]
// .at também funciona em strings
console.log("'hello'.at(-1) =", "hello".at(-1));
// ------------------------------------------------------------------------
// 2) findLast() e findLastIndex() (ECMAScript 2023)
// ------------------------------------------------------------------------
// simétricos a find() / findIndex()
const numbers: number[] = [5, 12, 8, 21, 3, 17];
const lastEven = numbers.findLast(n => n % 2 === 0);
console.log("last even number =", lastEven); // -> 8
const lastEvenIndex = numbers.findLastIndex(n => n % 2 === 0);
console.log("index of the last even number =", lastEvenIndex);
// ------------------------------------------------------------------------
// 3) os métodos "imutáveis" (ECMAScript 2023)
// ------------------------------------------------------------------------
// sort(), reverse(), splice() modificam o array original (efeito colateral) - cf arr-04.js
// seus equivalentes "to..." retornam um NOVO array e deixam o original intacto
// [(number | string)[]] porque toSpliced() insere strings neste array mais adiante
const original: (number | string)[] = [4, 5, 4, 2];
// toSorted: como sort(), mas sem modificar o original
const sorted = original.toSorted();
console.log("original =", original, " (unchanged)");
console.log("sorted =", sorted);
// toReversed: como reverse(), mas sem modificar o original
const reversed = original.toReversed();
console.log("reversed =", reversed, ", original still =", original);
// toSpliced: como splice(), mas sem modificar o original
// toSpliced(startIndex, countToDelete, ...elementos a inserir)
const modified: (number | string)[] = original.toSpliced(1, 2, "a", "b", "c");
console.log("modified =", modified, ", original still =", original);
// with(index, value): retorna uma cópia do array com um único elemento substituído
const replaced = original.with(0, 999);
console.log("replaced =", replaced, ", original still =", original);
// ------------------------------------------------------------------------
// por que é útil: esses métodos evitam efeitos colaterais, o que é
// particularmente apreciado em frameworks de front-end (React, Angular, Vue...)
// nos quais muitas vezes precisamos produzir um novo estado sem modificar o antigo.
// ------------------------------------------------------------------------
|
- [at(index)] (ES2022): acesso seguro e legível, inclusive com índices negativos (at(-1) = último elemento) — mais legível que arr[arr.length - 1];
- [findLast]/[findLastIndex] (ES2023): igual a find/findIndex, mas retorna o último elemento que satisfaz a condição;
- [toSorted], [toReversed], [toSpliced], [with] (ES2023): os equivalentes imutáveis de sort, reverse, splice e da atribuição por índice—retornam um novo array sem modificar o original, ao contrário dos métodos do script arr-03. Muito úteis em frameworks front-end (React, Vue...), nos quais é preciso produzir um novo estado sem modificar o anterior.
Resultado da execução:
| arr[arr.length - 1] = 50
arr.at(-1) = 50
arr.at(-2) = 40
arr.at(0) = 10
'hello'.at(-1) = o
last even number = 8
index of the last even number = 2
original = [ 4, 5, 4, 2 ] (unchanged)
sorted = [ 2, 4, 4, 5 ]
reversed = [ 2, 4, 5, 4 ] , original still = [ 4, 5, 4, 2 ]
modified = [ 4, 'a', 'b', 'c', 2 ] , original still = [ 4, 5, 4, 2 ]
replaced = [ 999, 5, 4, 2 ] , original still = [ 4, 5, 4, 2 ]
|
3.2.6. Conclusão
O principal ponto deste capítulo é que um array é um objeto referenciado por um ponteiro, sem tamanho fixo e dotado de um rico conjunto de métodos—alguns dos quais modificam o array no próprio lugar (push, sort…), enquanto outros, mais recentes, sempre retornam um novo array (toSorted, with…). O próximo capítulo trata dos objetos literais.
3.3. Objetos literais
Aqui, chamamos de “objetos literais” os objetos definidos diretamente no código, em oposição às instâncias de [class] (tratadas no capítulo “Classes”). Os scripts deste capítulo estão na pasta [objects] do projeto:

3.3.1. Script [obj-01]
Como nos arrays, um objeto é acessado por meio de um ponteiro. Em TypeScript, também é preciso definir a estrutura do objeto por meio de uma interface antes de poder acrescentar propriedades a ele dinamicamente.
| 'use strict';
// um objeto vazio
// interface: anunciamos antecipadamente as propriedades que vamos adicionar dinamicamente,
// porque o TypeScript (diferentemente do JavaScript) exige conhecer a forma de um objeto
interface Obj1 {
prop1?: string;
prop2?: number[];
prop3?: boolean;
[key: string]: unknown;
}
const obj1: Obj1 = {};
// as propriedades do objeto podem ser criadas dinamicamente
obj1.prop1 = "abcd";
console.log('obj1=', obj1);
// outra propriedade
obj1.prop2 = [1, 2, 3];
console.log("obj1=", obj1);
// outra propriedade com uma notação diferente
obj1['prop3'] = true;
console.log("obj1=", obj1);
// obj1 é uma referência ao objeto (ponteiro), não o objeto em si
const obj2: Obj1 = obj1;
// obj2 e obj1 apontam para o mesmo objeto
obj2.prop1 = "xyzt";
console.log("obj1=", obj1);
console.log("obj2=", obj2);
// as propriedades podem ser variáveis
const var1: string = 'prop1';
console.log('prop1=', obj1[var1]);
|
- Linhas 5–9: [interface] Obj1 declara antecipadamente as propriedades que serão acrescentadas (prop1, prop2, prop3, todas opcionais com ?). A linha [key: string]: unknown é uma assinatura de índice: ela permite também acrescentar qualquer outra propriedade não especificada antecipadamente;
- linha 19: obj1.prop3 também pode ser escrito como obj1['prop3']—essa notação é indispensável quando o nome da propriedade é, na verdade, o valor de uma variável (linhas 28–29);
- linhas 22–25:
const obj2: Obj1 = obj1 é uma cópia de referência, e não uma cópia do objeto—portanto, modificar obj2 também modifica o que se vê por meio de obj1, assim como nos arrays.
npx tsx objects/obj-01.ts
Resultado da execução:
| obj1= { prop1: 'abcd' }
obj1= { prop1: 'abcd', prop2: [ 1, 2, 3 ] }
obj1= { prop1: 'abcd', prop2: [ 1, 2, 3 ], prop3: true }
obj1= { prop1: 'xyzt', prop2: [ 1, 2, 3 ], prop3: true }
obj2= { prop1: 'xyzt', prop2: [ 1, 2, 3 ], prop3: true }
prop1= xyzt
|
3.3.2. Script [obj-02]
Este script demonstra um objeto de vários níveis e apresenta o objeto global [JSON], que converte um objeto em string e vice-versa.
| 'use strict';
// um objeto com vários níveis
interface PersonWithFamily {
firstName: string;
age: number;
father: { firstName: string; age: number };
mother: { firstName: string; age: number };
}
const person: PersonWithFamily = {
firstName: "martin",
age: 12,
father: {
firstName: "paul",
age: 45
},
mother: {
firstName: "micheline",
age: 42
}
}
// acesso às propriedades
console.log("person first name=", person.firstName);
console.log("mother first name=", person.mother.firstName);
person.mother.age = 40;
console.log("mother age=", person.mother.age);
// console.log pode exibir objetos
console.log("person=", person);
console.log("mother=", person.mother);
// também podemos exibir a string JSON do objeto
let json: string = JSON.stringify(person);
console.log("jSON=", json);
// podemos reler o JSON
let person2: PersonWithFamily = JSON.parse(json);
console.log("father=", person2.father);
|
- Linhas 3–8: uma [interface] pode conter, ela própria, tipos de objeto aninhados (father, mother);
- linha 30: [JSON.stringify] converte um objeto TypeScript em uma string JSON;
- linha 33: [JSON.parse] faz o inverso—observe que o resultado é do tipo PersonWithFamily, o que pressupõe que a string JSON realmente esteja em conformidade com esse formato (o TypeScript não verifica isso em tempo de execução, apenas em tempo de compilação).
npx tsx objects/obj-02.ts
Resultado da execução:
| person first name= martin
mother first name= micheline
mother age= 40
person= {
firstName: 'martin',
age: 12,
father: { firstName: 'paul', age: 45 },
mother: { firstName: 'micheline', age: 40 }
}
mother= { firstName: 'micheline', age: 40 }
jSON= {"firstName":"martin","age":12,"father":{"firstName":"paul","age":45},"mother":{"firstName":"micheline","age":40}}
father= { firstName: 'paul', age: 45 }
|
3.3.3. Script [obj-03]
Este script apresenta o conceito de getters e setters para a propriedade de um objeto:
| 'use strict';
// getters e setters de um objeto
interface PersonWithName {
_name?: string;
name: string;
}
const person: PersonWithName = {
// getter
get name() {
console.log("name getter");
return this._name as string;
},
// setter
set name(aName: string) {
console.log("name setter");
this._name = aName;
}
};
// setter
person.name = "Hercule";
// getter
console.log(person.name);
// o próprio objeto
console.log("person=", person);
// isso não impede o acesso direto à propriedade [_name]
person._name = "xyz";
console.log("person=", person);
|
- Linhas 3–6: a [interface] PersonWithName declara _name como uma propriedade opcional (prefixada com um sublinhado por convenção, para indicar que é uma propriedade “privada”, embora o TypeScript não impeça o acesso a ela—veja o encapsulamento verdadeiro com #field no capítulo “Classes”);
- linhas 8–11: [getter]—que usa a palavra-chave
get em vez de uma função—retorna o valor de _name;
- linhas 13–16: [setter]—que usa a palavra-chave
set—recebe o valor atribuído e pode validá-lo antes de armazená-lo;
- linha 20: person.name = "Hercule" chama o setter implicitamente;
- linha 22: person.name chama o getter implicitamente;
- linha 26: nada impede o acesso direto a _name—o encapsulamento por convenção depende da disciplina do desenvolvedor.
npx tsx objects/obj-03.ts
Resultado da execução:
| name setter
name getter
Hercule
person= { name: [Getter/Setter], _name: 'Hercule' }
person= { name: [Getter/Setter], _name: 'xyz' }
|
Observe que [console.log] exibe [Getter/Setter] para indicar que "name" é gerenciado por acessores, e não é um valor direto.
3.3.4. Script [obj-04]
Três formas de escrever o nome de uma propriedade, duas formas de acessá-la e uma notação abreviada:
| 'use strict';
// os nomes das propriedades de um objeto podem ser literais [name], entre apóstrofos ['name']
// ou entre aspas ["name"]
interface FullName {
lastName: string;
firstName: string;
}
// literal
const obj1: FullName = {
lastName: "martin",
firstName: "jean"
};
console.log("firstName=", obj1.firstName);
// entre apóstrofos
const obj2: FullName = {
'lastName': "martin",
'firstName': "jean"
};
console.log("lastName=", obj2.lastName);
// entre aspas
const obj3: FullName = {
"lastName": "martin",
"firstName": "jean"
};
// duas sintaxes possíveis para acessar a propriedade [lastName]
console.log("lastName=", obj3.lastName);
console.log("lastName=", obj3['lastName']);
// notação abreviada equivalente a {obj1:obj1, obj2:obj2}
const obj4 = {
obj1, obj2
}
console.log("obj4=", obj4)
|
- Os nomes de propriedade podem ser escritos literalmente (name:), entre aspas simples ('name':) ou entre aspas duplas ("name":)—as três formas são equivalentes;
- Linha 31: obj3.lastName and obj3['lastName'] acessam a mesma propriedade;
- Linhas 34–36:
const obj4 = { obj1, obj2 } é a notação abreviada de { obj1: obj1, obj2: obj2 }—muito usada ao agrupar variáveis existentes em um objeto.
npx tsx objects/obj-04.ts
Resultado da execução:
| firstName= jean
lastName= martin
lastName= martin
lastName= martin
obj4= {
obj1: { lastName: 'martin', firstName: 'jean' },
obj2: { lastName: 'martin', firstName: 'jean' }
}
|
3.3.5. Script [obj-05]
Um objeto literal pode ter propriedades do tipo função—isso nos aproxima do conceito de classe (propriedades + métodos):
| 'use strict';
// um objeto pode ter propriedades do tipo [function]
interface PersonWithToString {
firstName: string;
age: number;
father: { firstName: string; age: number };
mother: { firstName: string; age: number };
toString: () => string;
}
const person: PersonWithToString = {
// propriedades
firstName: "martin",
age: 12,
father: {
firstName: "paul",
age: 45
},
mother: {
firstName: "micheline",
age: 42
},
// método
toString: function () {
return JSON.stringify(this);
}
}
// uso
console.log("person=", person);
console.log("person.toString=", person.toString());
|
- linha 4: [interface] declara toString: () => string—o tipo de um método é declarado como o de uma propriedade do tipo função;
- linha 25: dentro do método, [this] refere-se ao próprio objeto—this.firstName é a propriedade “firstName” desse objeto.
npx tsx objects/obj-05.ts
Resultado da execução:
| person= {
firstName: 'martin',
age: 12,
father: { firstName: 'paul', age: 45 },
mother: { firstName: 'micheline', age: 42 },
toString: [Function: toString]
}
person.toString= {"firstName":"martin","age":12,"father":{"firstName":"paul","age":45},"mother":{"firstName":"micheline","age":42}}
|
3.3.6. Script [obj-06]
Este script demonstra como percorrer as propriedades de um objeto sem conhecer seus nomes de antemão:
| 'use strict';
// um objeto pode ter propriedades do tipo [function]
interface PersonWithToString {
firstName: string;
age: number;
father: { firstName: string; age: number };
mother: { firstName: string; age: number };
toString: () => string;
// assinatura de índice necessária para permitir o percurso dinâmico com for..in abaixo
[key: string]: unknown;
}
let person: PersonWithToString = {
// propriedades
firstName: "martin",
age: 12,
father: {
firstName: "paul",
age: 45
},
mother: {
firstName: "micheline",
age: 42
},
// método
toString: function () {
return JSON.stringify(this);
}
}
// uso
console.log(person);
// propriedades
console.log("-----------------------");
for (const key in person) {
// eslint-disable-next-line no-prototype-builtins
if (person.hasOwnProperty(key)) {
const element = person[key];
console.log(key, "=", element);
}
}
// para escapar do aviso do eslint (1)
console.log("-----------------------");
for (const key in person) {
if (Object.prototype.hasOwnProperty.call(person, key)) {
const element = person[key];
console.log(key, "=", element);
}
}
// para escapar do aviso do eslint (2)
console.log("-----------------------");
for (const key in person) {
// eslint-disable-next-line no-prototype-builtins
if (person.hasOwnProperty(key)) {
const element = person[key];
console.log(key, "=", element);
}
}
|
- Linha 11: a assinatura de índice [key: string]: unknown é necessária aqui para que o TypeScript permita o acesso dinâmico a person[key] dentro do laço for...in;
- Linhas 35–41:
for (const key in person) percorre os nomes das propriedades. O teste hasOwnProperty filtra eventuais propriedades herdadas (ausentes neste script, mas uma boa prática a seguir sistematicamente);
- este script oferece três formas equivalentes de escrever esse teste—a segunda (Object.prototype.hasOwnProperty.call(...)) é a mais robusta, enquanto a terceira apenas suprime o aviso correspondente do ESLint. Desde 2022, o método Object.hasOwn() (script obj-09, abaixo) tornou essa escolha desnecessária.
npx tsx objects/obj-06.ts
Resultado da execução:
| {
firstName: 'martin',
age: 12,
father: { firstName: 'paul', age: 45 },
mother: { firstName: 'micheline', age: 42 },
toString: [Function: toString]
}
-----------------------
firstName = martin
age = 12
father = { firstName: 'paul', age: 45 }
mother = { firstName: 'micheline', age: 42 }
toString = [Function: toString]
-----------------------
firstName = martin
age = 12
father = { firstName: 'paul', age: 45 }
mother = { firstName: 'micheline', age: 42 }
toString = [Function: toString]
-----------------------
firstName = martin
age = 12
father = { firstName: 'paul', age: 45 }
mother = { firstName: 'micheline', age: 42 }
toString = [Function: toString]
|
3.3.7. Script [obj-07]
Este script demonstra a desestruturação de objetos—uma sintaxe que extrai propriedades diretamente para variáveis:
| 'use strict';
// desestruturação
interface FullName {
lastName: string;
firstName: string;
}
// literal
const obj1: FullName = {
lastName: "martin",
firstName: "jean"
};
// desestruturação de obj1 nas variáveis [n,p]
const { lastName: n, firstName: p } = obj1;
console.log("n=", n, "p=", p);
// desestruturação de obj1 nas variáveis [n2,p2]
function f({ lastName: n2, firstName: p2 }: FullName): void {
console.log("f-n2=", n2, "f-p2=", p2);
}
f(obj1);
// desestruturação de obj1 nas variáveis [lastName,firstName]
function g({ lastName: lastName, firstName: firstName }: FullName): void {
console.log("g-lastName=", lastName, "g-firstName=", firstName);
}
g(obj1);
// desestruturação de obj1 nas variáveis [lastName,firstName]
// com notação abreviada equivalente a h({lastName:lastName,firstName:firstName})
function h({ lastName, firstName }: FullName): void {
console.log("h-lastName=", lastName, "h-firstName=", firstName);
}
h(obj1);
|
- linha 16: const { lastName: n, firstName: p } = obj1 cria duas variáveis n e p, equivalente a const n = obj1.lastName; const p = obj1.firstName;
- linhas 19–22, 24–27, 30–33: a desestruturação também funciona diretamente nos parâmetros de uma função—muito comum em TypeScript/React para extrair propriedades de um objeto de configuração ou de props;
- linha 33: function h({ lastName, firstName }: FullName) é uma abreviação de { lastName: lastName, firstName: firstName }—quando o nome da variável criada é idêntico ao nome da propriedade, ele pode ser omitido.
npx tsx objects/obj-07.ts
Resultado da execução:
| n= martin p= jean
f-n2= martin f-p2= jean
g-lastName= martin g-firstName= jean
h-lastName= martin h-firstName= jean
|
3.3.8. Script [obj-08]
Este script demonstra como criar uma cópia rasa de um objeto com o operador spread... :
| 'use strict'
// clonagem de objetos
interface FullName {
lastName: string;
firstName: string;
}
const obj1: FullName = {
lastName: "martin",
firstName: "jean"
};
// clone de obj1 com o operador spread
const obj2: FullName = { ...obj1 }
// verificações
// obj2 aponta para uma cópia de obj1
console.log("obj2===obj1 :", obj1 === obj2)
console.log("obj2=", obj2)
|
npx tsx objects/obj-08.ts
Resultado da execução:
| obj2===obj1 : false
obj2= { lastName: 'martin', firstName: 'jean' }
|
- obj2===obj1 resulta em false: as duas referências não apontam para o mesmo objeto;
- obj2 contém, de fato, uma cópia das propriedades de obj1—mas atenção: como veremos no próximo script, é apenas uma cópia rasa.
3.3.9. Script [obj-09]
[NOVO desde 2019] Este script demonstra três acréscimos úteis introduzidos desde 2020: [Object.hasOwn], [structuredClone] e a combinação de encadeamento opcional com coalescência nula em objetos aninhados.
| 'use strict';
// ========================================================================
// [NOVO desde 2019] manipulação de objetos: algumas adições práticas
// ========================================================================
// ------------------------------------------------------------------------
// 1) Object.hasOwn(object, property) (ECMAScript 2022)
// ------------------------------------------------------------------------
// antes, para saber se uma propriedade pertence diretamente a um objeto (e não é
// herdada pela cadeia de protótipos), escrevíamos:
// object.hasOwnProperty(property) -> pode falhar se o objeto redefinir hasOwnProperty
// Object.prototype.hasOwnProperty.call(object, property) -> correto, mas verboso (cf. objects/obj-06.js)
// [Object.hasOwn] faz esse trabalho de forma simples e sem riscos
interface FullName {
lastName: string;
firstName: string;
[key: string]: unknown;
}
const person: FullName = { lastName: "Dupont", firstName: "Jean" };
console.log("Object.hasOwn(person, 'lastName') =", Object.hasOwn(person, "lastName"));
console.log("Object.hasOwn(person, 'age') =", Object.hasOwn(person, "age"));
// uso típico em um percurso de propriedades
console.log("-----------------------");
for (const key in person) {
if (Object.hasOwn(person, key)) {
console.log(key, "=", person[key]);
}
}
// ------------------------------------------------------------------------
// 2) structuredClone(object) (API global disponível desde o node 17)
// ------------------------------------------------------------------------
// obj-08.js mostra a clonagem rasa com o operador spread [...obj]
// mas o spread só clona o 1º nível: os subobjetos continuam compartilhados!
interface PersonWithAddress {
lastName: string;
address: { city: string; postalCode: string };
}
const original: PersonWithAddress = {
lastName: "Dupont",
address: { city: "Nantes", postalCode: "44000" }
};
// clonagem rasa com spread
const shallowCopy: PersonWithAddress = { ...original };
shallowCopy.address.city = "Angers"; // também modifica o endereço de [original]!
console.log("shallow copy modified the original :", original.address.city === "Angers");
// reinicialização para o próximo teste
original.address.city = "Nantes";
// [structuredClone] faz uma clonagem profunda: todos os subobjetos são copiados
const deepCopy: PersonWithAddress = structuredClone(original);
deepCopy.address.city = "Angers";
console.log("deep copy did not modify the original :", original.address.city === "Nantes");
console.log("original =", original);
console.log("deepCopy =", deepCopy);
// ------------------------------------------------------------------------
// 3) encadeamento opcional + coalescência nula em métodos de objetos aninhados
// ------------------------------------------------------------------------
// combinação muito frequente na prática para ler uma configuração parcial
interface AppearanceConfiguration {
appearance?: { theme?: string };
}
function displayTheme(configuration?: AppearanceConfiguration): void {
// se configuration, configuration.appearance ou configuration.appearance.theme estiver ausente,
// recorremos a "light" sem nunca travar
const theme = configuration?.appearance?.theme ?? "light";
console.log("theme =", theme);
}
displayTheme({ appearance: { theme: "dark" } });
displayTheme({ appearance: {} });
displayTheme({});
displayTheme(undefined);
|
- [Object.hasOwn(object, property)] (ES2022) é um substituto melhor para object.hasOwnProperty(...) (veja o script obj-06): mais fácil de ler e nunca causa problemas se o próprio objeto redefinir hasOwnProperty;
- [structuredClone(object)] (disponível nativamente desde o Node 17) faz um clone profundo: ao contrário do spread { ...obj } do script obj-08, que copia apenas o primeiro nível, structuredClone copia também os subobjetos—modificar a cópia nunca modifica o original, em nenhum nível;
- a função displayTheme combina ?. e ?? para ler uma configuração de vários níveis, possivelmente incompleta, sem nunca falhar e com um valor de contingência claro.
npx tsx objects/obj-09.ts
Resultado da execução:
| Object.hasOwn(person, 'lastName') = true
Object.hasOwn(person, 'age') = false
-----------------------
lastName = Dupont
firstName = Jean
shallow copy modified the original : true
deep copy did not modify the original : true
original = { lastName: 'Dupont', address: { city: 'Nantes', postalCode: '44000' } }
deepCopy = { lastName: 'Dupont', address: { city: 'Angers', postalCode: '44000' } }
theme = dark
theme = light
theme = light
theme = light
|
3.3.10. Conclusão
Os scripts deste capítulo mostraram que o objeto literal do TypeScript se assemelha a uma instância de classe: é possível definir propriedades, métodos e getters/setters—com a vantagem adicional de uma [interface] que descreve com precisão sua forma em tempo de compilação. É um objeto dinâmico, comparável a um dicionário, cujos elementos podem ser de qualquer tipo, inclusive funções.
3.4. Strings
Os scripts deste capítulo estão na pasta [strings] do projeto:

3.4.1. Script [str-01]
A primeira coisa a entender é que, depois de criada, uma string não pode mais ser modificada (ela é imutável). Há muitos métodos disponíveis para criar uma nova string a partir da original, mas a string original permanece sempre inalterada.
| 'use strict';
// as strings são somente leitura (não podem ser modificadas)
// uma string
const string1: string = "abcd ";
// tipo
console.log("typeof(string1)=", typeof (string1));
// caractere nº 2
console.log("string1[2]=", string1[2]);
// provoca um erro
// [atualização TypeScript] o TypeScript detecta o erro em tempo de compilação:
// uma string só tem acesso de leitura por índice
// @ts-expect-error : uma string é somente leitura
string1[2] = "0";
|
- Linha 10: string1[2] lê o terceiro caractere da string (índice 0);
- linha 15: string1[2] = "0" tenta uma operação de escrita, que o TypeScript rejeita em tempo de compilação, graças a @ts-expect-error—o comentário acima confirma que esse erro é esperado e serve justamente para demonstrá-lo.
Verificação de tipos:
Resultado da execução:
| strings/str-01.ts(15,1): error TS2540: Cannot assign to '2' because it is a read-only property.
|
Execução com tsx (sem verificação prévia de tipos):
npx tsx strings/str-01.ts
Resultado da execução:
| typeof(string1)= string
string1[2]= c
TypeError: Cannot assign to read only property '2' of string 'abcd '
at strings/str-01.ts:15:10
|
3.4.2. Script [str-02]
Uma string pode ser de dois tipos: [string] (string literal) ou [object] (instância da classe [String]):
| 'use strict';
// as strings podem ser de dois tipos
// uma string literal
const string1: string = "abcd ";
// tipo
console.log("typeof(string1)=", typeof (string1));
// instância de String
// eslint-disable-next-line @typescript-eslint/ban-types - aqui [String] (objeto) é exatamente o tipo desejado, não [string] (primitivo): esse é justamente o assunto da demonstração
const string2: String = new String("xyzt");
// tipo
console.log("typeof(string2)=", typeof (string2));
// outra sintaxe (sem new)
const string3: string = String("12 34");
// tipo
console.log("typeof(string3)=", typeof (string3));
// o tipo [string] e o tipo [object] oferecem os mesmos métodos, os da classe String
console.log("string1.length=", string1.length);
console.log("string2.length=", string2.length);
|
- Linha 6: a forma padrão de definir uma string—string1 será do tipo string;
- Linha 11:
new String(...) cria um objeto string—string2 será do tipo object. Aqui, o tipo TypeScript declarado é String (com S maiúsculo), o tipo do *objeto wrapper*, que é diferente do tipo primitivo string (minúsculo);
- Os dois tipos oferecem os mesmos métodos—os da classe String.
npx tsx strings/str-02.ts
Resultado da execução:
| typeof(string1)= string
typeof(string2)= object
typeof(string3)= string
string1.length= 5
string2.length= 4
|
3.4.3. Script [str-03]
Este script demonstra a interpolação de variáveis em uma string:
| 'use strict';
// string
const string: string = "Introduction to Javascript by example";
// string com interpolação de variáveis
const str: string = `[${string}].substr(3, 2)=` + string.substr(3, 2)
console.log(str);
|
- Linha 6: uma string delimitada por crases (*backticks*, AltGr-7 em um teclado francês) pode conter expressões ${variable} , que são substituídas pelo valor da variável—isso se chama template string.
npx tsx strings/str-03.ts
Resultado da execução:
| [Introduction to Javascript by example].substr(3, 2)=ro
|
3.4.4. Script [str-04]
A template string, sozinha, não basta para uma formatação precisa (largura, alinhamento, precisão decimal etc.). Para isso, usamos um pacote externo, o [sprintf-js], que reproduz as funções printf/sprintf conhecidas de outras linguagens. Ele é instalado com npm install sprintf-js e pode ser importado facilmente:
| 'use strict';
// uso de um pacote externo para ter a função sprintf
import { sprintf } from 'sprintf-js';
// string
const string: string = "Introduction to Javascript by example";
// método
console.log(sprintf("[%s].substr(3,2)=[%s]", string, string.substr(3, 2)));
|
Contexto: em 2019, a instrução `import` causava problemas com o Node.js (que ainda não suportava nativamente módulos ECMAScript) e exigia um pacote intermediário chamado `esm`. Isso não acontece mais desde o Node 12+: nosso projeto, com "type": "module" no package.json, usa import/export nativamente, sem nenhuma configuração adicional.
npx tsx strings/str-04.ts
Resultado da execução:
| [Introduction to Javascript by example].substr(3,2)=[ro]
|
3.4.5. Script [str-05]
A função [sprintf] aceita, como em C, "formatos" introduzidos por %: %s (string), %d (inteiro), %f (ponto flutuante), %j (JSON), %T (tipo), %t (booleano), além de modificadores de largura e alinhamento (%20s, %-20s, %04d...):
| 'use strict';
// uso de um pacote externo para ter a função sprintf
import { sprintf } from 'sprintf-js';
// string
const string: string = "Javascript";
// strings
console.log(sprintf("[%s, %%s]=>[%s]", string, string));
console.log(sprintf("[%s, %%20s]=>[%20s]", string, string));
console.log(sprintf("[%s, %%-20s]=>[%-20s]", string, string));
// inteiros
console.log(sprintf("[%d, %%d]=>[%d]", 10, 10));
console.log(sprintf("[%d, %%4d]=>[%4d]", 10, 10));
console.log(sprintf("[%d, %%-4d]=>[%-4d]", 10, 10));
console.log(sprintf("[%d, %%04d]=>[%04d]", 10, 10));
// reais
console.log(sprintf("[%f, %%f]=>[%f]", -10.5, -10.5));
console.log(sprintf("[%f, %%10.2f]=>[%10.2f]", -10.5, -10.5));
console.log(sprintf("[%f, %%-10.2f]=>[%-10.2f]", -10.5, -10.5));
console.log(sprintf("[%f, %%010.3f]=>[%010.3f]", -10.5, -10.5));
// json
console.log(sprintf("person (%%j)=%j", { name: "mathieu", age: 34 }));
// tipo
console.log(sprintf("person type (%%T)=%T", { name: "mathieu", age: 34 }));
// booleano
console.log(sprintf("boolean (%%t)=%t", 4 === 4));
|
npx tsx strings/str-05.ts
Resultado da execução:
| [Javascript, %s]=>[Javascript]
[Javascript, %20s]=>[ Javascript]
[Javascript, %-20s]=>[Javascript ]
[10, %d]=>[10]
[10, %4d]=>[ 10]
[10, %-4d]=>[10 ]
[10, %04d]=>[0010]
[-10.5, %f]=>[-10.5]
[-10.5, %10.2f]=>[ -10.50]
[-10.5, %-10.2f]=>[-10.50 ]
[-10.5, %010.3f]=>[-00010.500]
person (%j)={"name":"mathieu","age":34}
person type (%T)=object
boolean (%t)=true
|
3.4.6. Script [str-06]
Este script lista os métodos mais comuns da classe [String]:
| 'use strict';
// uso de um pacote externo para ter a função sprintf
import { sprintf } from 'sprintf-js';
// string
const string: string = " Introduction to Javascript ";
// alguns métodos
// substr(10,2): 2 caracteres a partir do nº 10
console.log(sprintf("[%s].substr(10,2)=[%s]", string, string.substr(10, 2)));
// trim: remoção dos espaços em branco no início e no fim da string (espaço em branco=\b \t \r \n \f)
console.log(sprintf("[%s].trim()=[%s]", string, string.trim()));
// toLowerCase: conversão para minúsculas
console.log(sprintf("[%s].toLowerCase=[%s]", string, string.toLowerCase()));
// toUpperCase: conversão para maiúsculas
console.log(sprintf("[%s].toUpperCase=[%s]", string, string.toUpperCase()));
// indexOf: posição de uma string procurada na string, -1 se a substring não existir
console.log(sprintf("[%s].indexOf('Java')=[%s]", string, string.indexOf('Java')));
console.log(sprintf("[%s].trim().indexOf('abcd')=[%s]", string, string.indexOf('abcd')));
// includes: true se a string procurada estiver na string
console.log(sprintf("[%s].includes('Java')=[%s]", string, string.includes('Java')));
// length: comprimento da string - não é um método, mas uma propriedade
console.log(sprintf("[%s].length=[%s]", string, string.length));
// slice (7,10): string dos caracteres nº 7 a 9
console.log(sprintf("[%s].slice(7,10)=[%s]", string, string.slice(7, 10)));
// match: procura uma expressão na string - essa expressão pode ser uma expressão regular
// /intro/i: expressão regular designando a string [intro] em maiúsculas ou minúsculas
// retorna a string encontrada
console.log(sprintf("[%s].match(/intro/i)=[%s]", string, string.match(/intro/i)));
// replace: substitui string1 por string2 em string
// substitui a 1ª ocorrência de i por x
console.log(sprintf("[%s].replace('i','x')=[%s]", string, string.replace('i', 'x')));
// substitui todas as ocorrências de i por x
// /i/g é uma expressão regular designando todas (g) as ocorrências de i
console.log(sprintf("[%s].replace(/i/g,'x')=[%s]", string, string.replace(/i/g, 'x')));
// split: divide a string em palavras separadas pelo parâmetro de split
// retorna o array dessas palavras
// regex \s* entre barras: palavras separadas por 0 ou mais espaços
console.log(sprintf("[%s].split(/\\s*/)=[%s]", string, string.split(/\s*/)));
// /\s+/: palavras separadas por um ou mais espaços
console.log(sprintf("[%s].split(/\\s+/)=[%s]", string, string.split(/\s+/)));
|
- [trim] remove os espaços em branco no início e no fim; [toLowerCase]/[toUpperCase] alteram a caixa;
- [indexOf] retorna a posição de uma substring (-1 se ausente); [includes] retorna um booleano;
- [slice] extrai uma substring por posição; [match] compara a string com uma expressão regular (veja o próximo capítulo);
- [replace] substitui a primeira ocorrência encontrada (ou todas as ocorrências, com uma regex /g); [split] divide a string em um array de palavras.
npx tsx strings/str-06.ts
Resultado da execução:
| [ Introduction to Javascript ].substr(10,2)=[ti]
[ Introduction to Javascript ].trim()=[Introduction to Javascript]
[ Introduction to Javascript ].toLowerCase=[ introduction to javascript ]
[ Introduction to Javascript ].toUpperCase=[ INTRODUCTION TO JAVASCRIPT ]
[ Introduction to Javascript ].indexOf('Java')=[18]
[ Introduction to Javascript ].trim().indexOf('abcd')=[-1]
[ Introduction to Javascript ].includes('Java')=[true]
[ Introduction to Javascript ].length=[29]
[ Introduction to Javascript ].slice(7,10)=[duc]
[ Introduction to Javascript ].match(/intro/i)=[Intro]
[ Introduction to Javascript ].replace('i','x')=[ Introductxon to Javascript ]
[ Introduction to Javascript ].replace(/i/g,'x')=[ Introductxon to Javascrxpt ]
[ Introduction to Javascript ].split(/\s*/)=[,I,n,t,r,o,d,u,c,t,i,o,n,t,o,J,a,v,a,s,c,r,i,p,t,]
[ Introduction to Javascript ].split(/\s+/)=[,Introduction,to,Javascript,]
|
3.4.7. Script [str-07]
[NOVO desde 2019] Três novidades introduzidas entre 2020 e 2024: [replaceAll], [matchAll] e a detecção/correção de strings “malformadas”:
| 'use strict';
// ========================================================================
// [NOVO desde 2019] novos métodos de string
// ========================================================================
// ------------------------------------------------------------------------
// 1) replaceAll(search, replace) (ECMAScript 2021)
// ------------------------------------------------------------------------
// str-06.js mostra que replace() com uma string só substitui a 1ª ocorrência
// e que era preciso usar uma expressão regular /i/g para substituir tudo
const string: string = "one cat, two cats, three cats";
console.log("replace (only 1 occurrence) :", string.replace("cat", "dog"));
console.log("replaceAll (all the occurrences) :", string.replaceAll("cat", "dog"));
// replaceAll também aceita uma expressão regular, mas ela deve ter então a flag [g]
console.log("replaceAll with regexp :", string.replaceAll(/cat/g, "dog"));
// ------------------------------------------------------------------------
// 2) matchAll(regexp) (ECMAScript 2020)
// ------------------------------------------------------------------------
// match() com a flag [g] só retorna as strings encontradas, sem sua posição nem seus grupos
// matchAll() retorna um iterador que fornece, para cada ocorrência, todas as informações (como exec())
const text: string = "Jean is 30 years old, Marie is 25 years old, Paul is 40 years old";
const pattern: RegExp = /(\w+) is (\d+) years old/g;
// com match (flag g): perdemos o detalhe dos grupos capturados
console.log("match =", text.match(pattern));
// com matchAll: mantemos o detalhe (nome capturado, idade capturada, posição...)
console.log("-----------------------");
for (const result of text.matchAll(pattern)) {
console.log("name =", result[1], ", age =", result[2], ", position =", result.index);
}
// também podemos transformar o iterador em array graças ao operador spread
const allResults = [...text.matchAll(pattern)];
console.log("number of matches =", allResults.length);
// ------------------------------------------------------------------------
// 3) isWellFormed() / toWellFormed() (ECMAScript 2024)
// ------------------------------------------------------------------------
// uma string JavaScript pode conter uma "meia-letra unicode" isolada inválida
// (por exemplo, quando uma string foi cortada incorretamente). Isso pode fazer
// algumas funções travarem (encodeURIComponent, ...)
const validString: string = "café ☕";
const malformedString: string = "abc\uD800def"; // \uD800 é uma "meia-letra" isolada, inválida por si só
console.log("validString.isWellFormed() =", validString.isWellFormed());
console.log("malformedString.isWellFormed() =", malformedString.isWellFormed());
// toWellFormed() substitui os caracteres inválidos pelo caractere de substituição �
console.log("malformedString.toWellFormed() =", malformedString.toWellFormed());
|
- [replaceAll] (ES2021) substitui todas as ocorrências de uma string sem exigir uma expressão regular /g, como no script str-06;
- [matchAll] (ES2020) retorna um iterador com todos os resultados encontrados, cada um com seus grupos capturados e sua posição (index)—enquanto um match com a flag
g retorna apenas as strings encontradas, sem esse detalhe;
- [isWellFormed]/[toWellFormed] (ES2024) detectam e corrigem strings que contêm um “meio caractere Unicode” isolado (frequentemente causado por uma divisão incorreta da string), o que pode fazer certas funções—como encodeURIComponent—falharem.
npx tsx strings/str-07.ts
Resultado da execução:
| replace (only 1 occurrence) : one dog, two cats, three cats
replaceAll (all the occurrences) : one dog, two dogs, three dogs
replaceAll with regexp : one dog, two dogs, three dogs
match = [ 'Jean is 30 years old', 'Marie is 25 years old', 'Paul is 40 years old' ]
-----------------------
name = Jean , age = 30 , position = 0
name = Marie , age = 25 , position = 22
name = Paul , age = 40 , position = 45
number of matches = 3
validString.isWellFormed() = true
malformedString.isWellFormed() = false
malformedString.toWellFormed() = abc�def
|
3.5. Expressões regulares
Os scripts deste capítulo estão na pasta [regexp] do projeto. Tanto em TypeScript quanto em JavaScript, uma expressão regular não é uma string , mas um objeto por si só, do tipo RegExp—portanto, não se coloca uma expressão regular entre aspas.

3.5.1. Script [regexp-01]
Este script compara várias strings com diferentes padrões (uma sequência de dígitos, uma data dd/mm/aa, um número decimal) e recupera os grupos encontrados:
| 'use strict';
/// expressões regulares em javascript
// recuperação dos diversos campos de uma string
// o padrão: uma sequência de dígitos cercada por quaisquer caracteres
// queremos recuperar apenas a sequência de dígitos
let pattern: RegExp = /(\d+)/;
console.log("type of a regular expression : ", typeof (pattern));
// comparamos a string com o padrão
comparePatternToString(pattern, "xyz1234abcd");
comparePatternToString(pattern, "12 34");
comparePatternToString(pattern, "abcd");
// o padrão: uma sequência de dígitos cercada por quaisquer caracteres
// queremos a sequência de dígitos, bem como os campos que a seguem e a precedem
pattern = /^(.*?)(\d+)(.*?)$/;
// comparamos a string com o padrão
comparePatternToString(pattern, "xyz1234abcd");
comparePatternToString(pattern, "12 34");
comparePatternToString(pattern, "abcd");
// o padrão - uma data no formato dd/mm/aa
pattern = /^\s*(\d\d)\/(\d\d)\/(\d\d)\s*$/;
comparePatternToString(pattern, "10/05/97");
comparePatternToString(pattern, " 04/04/01 ");
comparePatternToString(pattern, "5/1/01");
// o padrão - um número decimal
pattern = /^\s*([+|-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*$/;
comparePatternToString(pattern, "187.8");
comparePatternToString(pattern, "-0.6");
comparePatternToString(pattern, "4");
comparePatternToString(pattern, ".6");
comparePatternToString(pattern, "4.");
comparePatternToString(pattern, " + 4");
// --------------------------------------------------------------------------
function comparePatternToString(pattern: RegExp, str: string): void {
// compara a string [str] com o padrão [pattern]
console.log(`----------- string=${str}, pattern=${pattern}`)
// comparamos a string com o padrão
const result1 = pattern.exec(str);
console.log(`comparison with exec=`, result1);
// outra maneira de fazer
const result2 = str.match(pattern);
console.log(`comparison with match=`, result2);
}
|
- linha 7: let pattern: RegExp = /(\d+)/ — o tipo RegExp é explícito aqui, mas o TypeScript o teria deduzido automaticamente a partir da sintaxe /.../ de qualquer forma;
- Os métodos [pattern.exec(str)] e [str.match(pattern)] retornam o mesmo resultado: ou null (sem correspondência) ou um array em que:
- o elemento [0] é a string inteira que corresponde ao padrão;
- os elementos [1], [2]... correspondem aos grupos capturados entre parênteses, em ordem;
- a propriedade .index retorna a posição da correspondência dentro da string;
- a propriedade .input retorna a string original.
npx tsx regexp/regexp-01.ts
Resultado da execução:
| type of a regular expression : object
----------- string=xyz1234abcd, pattern=/(\d+)/
comparison with exec= [ '1234', '1234', index: 3, input: 'xyz1234abcd', groups: undefined ]
comparison with match= [ '1234', '1234', index: 3, input: 'xyz1234abcd', groups: undefined ]
----------- string=12 34, pattern=/(\d+)/
comparison with exec= [ '12', '12', index: 0, input: '12 34', groups: undefined ]
comparison with match= [ '12', '12', index: 0, input: '12 34', groups: undefined ]
----------- string=abcd, pattern=/(\d+)/
comparison with exec= null
comparison with match= null
----------- string=xyz1234abcd, pattern=/^(.*?)(\d+)(.*?)$/
comparison with exec= [ 'xyz1234abcd', 'xyz', '1234', 'abcd', index: 0, input: 'xyz1234abcd', groups: undefined ]
comparison with match= [ 'xyz1234abcd', 'xyz', '1234', 'abcd', index: 0, input: 'xyz1234abcd', groups: undefined ]
----------- string=12 34, pattern=/^(.*?)(\d+)(.*?)$/
comparison with exec= [ '12 34', '', '12', ' 34', index: 0, input: '12 34', groups: undefined ]
comparison with match= [ '12 34', '', '12', ' 34', index: 0, input: '12 34', groups: undefined ]
----------- string=abcd, pattern=/^(.*?)(\d+)(.*?)$/
comparison with exec= null
comparison with match= null
----------- string=10/05/97, pattern=/^\s*(\d\d)\/(\d\d)\/(\d\d)\s*$/
comparison with exec= [ '10/05/97', '10', '05', '97', index: 0, input: '10/05/97', groups: undefined ]
comparison with match= [ '10/05/97', '10', '05', '97', index: 0, input: '10/05/97', groups: undefined ]
----------- string= 04/04/01 , pattern=/^\s*(\d\d)\/(\d\d)\/(\d\d)\s*$/
comparison with exec= [ ' 04/04/01 ', '04', '04', '01', index: 0, input: ' 04/04/01 ', groups: undefined ]
comparison with match= [ ' 04/04/01 ', '04', '04', '01', index: 0, input: ' 04/04/01 ', groups: undefined ]
----------- string=5/1/01, pattern=/^\s*(\d\d)\/(\d\d)\/(\d\d)\s*$/
comparison with exec= null
comparison with match= null
----------- string=187.8, pattern=/^\s*([+|-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*$/
comparison with exec= [ '187.8', '', '187.8', index: 0, input: '187.8', groups: undefined ]
comparison with match= [ '187.8', '', '187.8', index: 0, input: '187.8', groups: undefined ]
----------- string=-0.6, pattern=/^\s*([+|-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*$/
comparison with exec= [ '-0.6', '-', '0.6', index: 0, input: '-0.6', groups: undefined ]
comparison with match= [ '-0.6', '-', '0.6', index: 0, input: '-0.6', groups: undefined ]
----------- string=4, pattern=/^\s*([+|-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*$/
comparison with exec= [ '4', '', '4', index: 0, input: '4', groups: undefined ]
comparison with match= [ '4', '', '4', index: 0, input: '4', groups: undefined ]
----------- string=.6, pattern=/^\s*([+|-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*$/
comparison with exec= [ '.6', '', '.6', index: 0, input: '.6', groups: undefined ]
comparison with match= [ '.6', '', '.6', index: 0, input: '.6', groups: undefined ]
----------- string=4., pattern=/^\s*([+|-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*$/
comparison with exec= [ '4.', '', '4.', index: 0, input: '4.', groups: undefined ]
comparison with match= [ '4.', '', '4.', index: 0, input: '4.', groups: undefined ]
----------- string= + 4, pattern=/^\s*([+|-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*$/
comparison with exec= [ ' + 4', '+', '4', index: 0, input: ' + 4', groups: undefined ]
comparison with match= [ ' + 4', '+', '4', index: 0, input: ' + 4', groups: undefined ]
|
3.5.2. Script [regexp-02]
Às vezes, você não quer extrair elementos da string testada, mas apenas saber se ela corresponde ao padrão. Nesse caso, use [RegExp.test] em vez de exec/match, e você pode remover os parênteses de captura, que deixam de ser necessários:
| 'use strict';
/// expressões regulares em javascript
// recuperação dos diversos campos de uma string
// o padrão: uma sequência de dígitos cercada por quaisquer caracteres
// queremos recuperar apenas a sequência de dígitos
let pattern: RegExp = /\d+/;
console.log("type of a regular expression : ", typeof (pattern));
// comparamos a string com o padrão
comparePatternToString(pattern, "xyz1234abcd");
comparePatternToString(pattern, "12 34");
comparePatternToString(pattern, "abcd");
// o padrão: uma sequência de dígitos cercada por quaisquer caracteres
// queremos a sequência de dígitos, bem como os campos que a seguem e a precedem
pattern = /^.*?\d+.*?$/;
// comparamos a string com o padrão
comparePatternToString(pattern, "xyz1234abcd");
comparePatternToString(pattern, "12 34");
comparePatternToString(pattern, "abcd");
// o padrão - uma data no formato dd/mm/aa
pattern = /^\s*\d\d\/\d\d\/\d\d\s*$/;
comparePatternToString(pattern, "10/05/97");
comparePatternToString(pattern, " 04/04/01 ");
comparePatternToString(pattern, "5/1/01");
// o padrão - um número decimal
pattern = /^\s*[+|-]?\s*\d+\.\d*|\.\d+|\d+\s*$/;
comparePatternToString(pattern, "187.8");
comparePatternToString(pattern, "-0.6");
comparePatternToString(pattern, "4");
comparePatternToString(pattern, ".6");
comparePatternToString(pattern, "4.");
comparePatternToString(pattern, " + 4");
// --------------------------------------------------------------------------
function comparePatternToString(pattern: RegExp, str: string): void {
// teste
const matches = pattern.test(str);
// compara a string [str] com o padrão [pattern]
console.log(`----------- string=${str}, pattern=${pattern}, matches=${matches}`);
}
|
npx tsx regexp/regexp-02.ts
Resultado da execução:
| type of a regular expression : object
----------- string=xyz1234abcd, pattern=/\d+/, matches=true
----------- string=12 34, pattern=/\d+/, matches=true
----------- string=abcd, pattern=/\d+/, matches=false
----------- string=xyz1234abcd, pattern=/^.*?\d+.*?$/, matches=true
----------- string=12 34, pattern=/^.*?\d+.*?$/, matches=true
----------- string=abcd, pattern=/^.*?\d+.*?$/, matches=false
----------- string=10/05/97, pattern=/^\s*\d\d\/\d\d\/\d\d\s*$/, matches=true
----------- string= 04/04/01 , pattern=/^\s*\d\d\/\d\d\/\d\d\s*$/, matches=true
----------- string=5/1/01, pattern=/^\s*\d\d\/\d\d\/\d\d\s*$/, matches=false
----------- string=187.8, pattern=/^\s*[+|-]?\s*\d+\.\d*|\.\d+|\d+\s*$/, matches=true
----------- string=-0.6, pattern=/^\s*[+|-]?\s*\d+\.\d*|\.\d+|\d+\s*$/, matches=true
----------- string=4, pattern=/^\s*[+|-]?\s*\d+\.\d*|\.\d+|\d+\s*$/, matches=true
----------- string=.6, pattern=/^\s*[+|-]?\s*\d+\.\d*|\.\d+|\d+\s*$/, matches=true
----------- string=4., pattern=/^\s*[+|-]?\s*\d+\.\d*|\.\d+|\d+\s*$/, matches=true
----------- string= + 4, pattern=/^\s*[+|-]?\s*\d+\.\d*|\.\d+|\d+\s*$/, matches=true
|
3.6. As funções
Os scripts deste capítulo estão na pasta [functions] do projeto:

3.6.1. Script [func-01]
Este script trata de como os parâmetros são passados a uma função: por valor para números, strings e booleanos; por referência para arrays, objetos literais e funções.
| 'use strict';
// como os parâmetros de função são passados
// - número - passagem por valor
function doSomethingWithNumber(param: number): void {
param++;
console.log("[param inside function]=", param, "[type]=", typeof (param), "[pass by reference]=", param === count);
}
// código chamador
let count: number = 10;
doSomethingWithNumber(count);
console.log("[count outside function]=", count);
// - string - passagem por valor
function doSomethingWithString(param: string): void {
param += " xyz"
console.log("[param inside function]=", param, "[type]=", typeof (param), "[pass by reference]=", param === text);
}
// código chamador
let text: string = "abcd";
doSomethingWithString(text);
console.log("[text outside function]=", text);
// - booleano - passagem por valor
function doSomethingWithBoolean(param: boolean): void {
param = !param;
console.log("[param inside function]=", param, "[type]=", typeof (param), "[pass by reference]=", param === bool);
}
// código chamador
let bool: boolean = true;
doSomethingWithBoolean(bool);
console.log("bool [outside function]=", bool);
// - array - passagem por referência
function doSomethingWithArray(param: number[]): void {
param.push(1000);
console.log("[param inside function]=", param, "[type]=", typeof (param), "[pass by reference]=", param === arr);
}
// código chamador
const arr: number[] = [10, 20, 30];
doSomethingWithArray(arr);
console.log("[arr outside function]=", arr);
// - objeto - passagem por referência
// [any] para poder adicionar dinamicamente [aNewProperty], como em JS
function doSomethingWithObject(param: any): void {
param.aNewProperty = "xyz";
console.log("[param inside function]=", param, "[type]=", typeof (param), "[pass by reference]=", param === obj);
}
// código chamador
const obj: any = [10, 20, 30];
doSomethingWithObject(obj);
console.log("[obj outside function]=", obj);
// - função - passagem por referência
// [any] porque atribuímos dinamicamente uma propriedade à própria função (veja abaixo)
function doSomethingWithFunction(param: any): void {
// algo bastante estranho que, mesmo assim, funciona
param.aNewProperty = "xyz";
console.log("[param inside function]=", param, "[type]=", typeof (param), "[pass by reference]=", param === f);
}
// código chamador
const f: any = (x: number) => x + 4;
doSomethingWithFunction(f);
console.log("[f outside function]=", f, f.aNewProperty, typeof (f));
|
- Os tipos primitivos (number, string, boolean) são passados por valor: modificar
param dentro da função nunca altera a variável original (pass-by-reference = false em cada caso);
- arrays, objetos e funções são passados por referência:
param === arr (ou obj, ou f) resulta em true, e uma modificação feita dentro da função fica claramente visível fora dela;
- linha 45: function doSomethingWithObject(param: any) — tipada como
any porque uma propriedade (aNewProperty) não prevista no tipo original do array obj é acrescentada dinamicamente;
- linha 58: o mesmo vale para doSomethingWithFunction — uma propriedade é acrescentada à própria função; esse comportamento (do JavaScript) é um pouco confuso, mas perfeitamente válido (uma função também é um objeto).
npx tsx functions/func-01.ts
Resultado da execução:
| [param inside function]= 11 [type]= number [pass by reference]= false
[count outside function]= 10
[param inside function]= abcd xyz [type]= string [pass by reference]= false
[text outside function]= abcd
[param inside function]= false [type]= boolean [pass by reference]= false
bool [outside function]= true
[param inside function]= [ 10, 20, 30, 1000 ] [type]= object [pass by reference]= true
[arr outside function]= [ 10, 20, 30, 1000 ]
[param inside function]= [ 10, 20, 30, aNewProperty: 'xyz' ] [type]= object [pass by reference]= true
[obj outside function]= [ 10, 20, 30, aNewProperty: 'xyz' ]
[param inside function]= [Function: f] { aNewProperty: 'xyz' } [type]= function [pass by reference]= true
[f outside function]= [Function: f] { aNewProperty: 'xyz' } xyz function
|
3.6.2. Script [func-02]
Este script mostra que [function] é um tipo de dados como qualquer outro: uma variável pode ter esse tipo, e há duas formas de definir uma função—com a palavra-chave function ou com a notação de seta =>.
| 'use strict';
// uma função pode ser atribuída a uma variável
const variable1: (a: number, b: number) => number = function (a, b) {
return a + b;
};
console.log("typeof(variable1)=", typeof (variable1));
// a variável pode então ser usada como uma função
console.log("variable1(10,12)=", variable1(10, 12));
// a função pode ser definida com a notação =>
const variable2: (a: number, b: number, c: number) => number = (a, b, c) => {
return a - b + c;
};
console.log("variable2(10,12,14)=", variable2(10, 12, 14));
// as chaves podem ser omitidas se houver apenas uma expressão no código da função
// essa expressão é então o valor de retorno da função
const variable3 = (a: number, b: number, c: number): number => a + b + c;
console.log("variable3(10,12,14)=", variable3(10, 12, 14));
|
- linha 3: const variable1: (a: number, b: number) => number = function (a, b) {...} — o tipo de uma variável de função é declarado como uma assinatura (parameters) => returnType;
- linhas 10–12: o mesmo, usando a notação de seta (a, b, c) => { ... };
- linha 16: sem chaves, o corpo da função se reduz a uma única expressão, que se torna automaticamente o valor de retorno — (a, b, c): number => a + b + c.
npx tsx functions/func-02.ts
Resultado da execução:
| typeof(variable1)= function
variable1(10,12)= 22
variable2(10,12,14)= 12
variable3(10,12,14)= 36
|
3.6.3. Script [func-03]
Este script demonstra que uma função pode ser passada como argumento a outra função—uma técnica muito usada nos frameworks TypeScript/JavaScript (callbacks, map/filter/reduce do capítulo “Arrays”...):
| 'use strict';
// os parâmetros de uma função podem ser do tipo [function]
// função f1
function f1(param1: number, param2: number): number {
return param1 + param2 + 10;
}
// função f2
function f2(param1: number, param2: number): number {
return param1 + param2 + 20;
}
// função g com uma função f como parâmetro
function g(param1: number, param2: number, f: (a: number, b: number) => number): number {
return f(param1, param2) + 100;
}
// usos de g
console.log(g(0, 10, f1));
console.log(g(0, 10, f2));
// o parâmetro efetivo do tipo função pode ser passado diretamente - forma 1
console.log(g(0, 10, (param1, param2) => {
return param1 + param2 + 30;
}));
// o parâmetro efetivo do tipo função pode ser passado diretamente - forma 2
console.log(g(0, 10, function (param1, param2) {
return param1 + param2 + 40;
}));
|
- linha 13: function g(param1: number, param2: number, f: (a: number, b: number) => number): number — o terceiro parâmetro, f, é ele próprio tipado como uma função;
- linhas 20–22 e 24–26: o parâmetro do tipo função pode ser passado diretamente, seja como uma arrow function, seja como uma função comum, sem antes ser armazenado em uma variável.
npx tsx functions/func-03.ts
Resultado da execução:
3.6.4. Script [func-04]
Este script demonstra que uma função pode se comportar como uma classe—um mecanismo anterior ao ES6 mas ainda válido, embora hoje tenha sido substituído pela palavra-chave class (veja o capítulo “Classes”):
| 'use strict';
// uma função pode ser usada como um objeto
// uma casca vazia
// [any]: o tipo de [this] é deliberadamente flexível aqui, porque atribuímos
// propriedades à própria função DEPOIS de sua definição (veja abaixo) -
// um padrão que o TypeScript não consegue inferir sozinho
function f(this: any): void {
}
// à qual atribuímos propriedades externamente
(f as any).prop1 = "val1";
(f as any).show = function (this: any) {
console.log(this.prop1);
};
// uso de f
(f as any).show();
// uma função g que funciona como uma classe
function g(this: any): void {
this.prop2 = "val2";
this.show = function (this: any) {
console.log(this.prop2);
};
}
// instanciação da função com [new]
new (g as any)().show();
|
- linhas 5–10: f é uma função “casca vazia”, tipada com
this: any—essa anotação especial no primeiro parâmetro informa ao TypeScript o tipo dethis` dentro da função, o que é necessário aqui porque propriedades são acrescentadas a ela do lado de fora, um padrão que o TypeScript não consegue deduzir sozinho;
- linhas 12–15: propriedades são atribuídas a f do lado de fora — (f as any).prop1 = ...;
- Linha 17: chamamos f.show(), e não f()—essa é, de fato, a notação de uso de um objeto, não de uma chamada de função comum;
- Linhas 20–25: g define this.prop2 e this.show dentro de si mesma, exatamente como faria o construtor de uma classe;
- linha 27:
new (g as any)() **instancia **g como uma classe.
npx tsx functions/func-04.ts
Resultado da execução:
Nota: o ES6 introduziu a palavra-chave `class` (veja o capítulo “Classes”), que permite obter esse resultado diretamente, sem recorrer a esse artifício funcional.
3.6.5. Script [func-05]
Este script demonstra o uso do [operador rest] (...), que reúne em um array todos os argumentos restantes de uma chamada:
| 'use strict';
// operador rest
function f(arg1: number, ...otherArgs: unknown[]): void {
// 1º argumento
console.log("arg1=", arg1);
// os demais argumentos
let i = 0;
otherArgs.forEach(element => {
console.log("otherArguments[", i, "]=", element);
i++;
});
}
// chamada
f(1, "two", "three", { x: 2, y: 3 })
|
- linha 3: function f(arg1: number, ...otherArgs: unknown[]): void — otherArgs reúne todos os argumentos passados depois de arg1, qualquer que seja o seu número. O tipo
unknown[] é apropriado aqui porque otherArgs mistura intencionalmente tipos diferentes (strings e objetos, na chamada da linha 15).
npx tsx functions/func-05.ts
Resultado da execução:
| arg1= 1
otherArguments[ 0 ]= two
otherArguments[ 1 ]= three
otherArguments[ 2 ]= { x: 2, y: 3 }
|
3.7. Erros e exceções
O TypeScript herda do JavaScript o sistema de tratamento de exceções, que é bastante básico: a instrução [throw] sinaliza um erro, e a estrutura [try / catch / finally] o captura. Os scripts deste capítulo estão na pasta [exceptions] do projeto.

3.7.1. Script [excep-01]
Este script exibe a hora atual no formato horas:minutos:segundos:milissegundos usando a biblioteca [moment.js] (npm install moment) e, em seguida, demonstra como try/catch/finally funciona, provocando um erro conforme a paridade dos milissegundos atuais:
| 'use strict';
// pacote moment
import moment from 'moment';
// princípio de try / catch / finally
for (let i = 0; i < 10; i++) {
// data - hora do momento atual
const now = Date.now();
// formatação da hora para obter os milissegundos
const time = moment(now).format("HH:mm:ss:SSS");
// os milissegundos
const milli = Number(time.substr(time.length - 3));
// exibição
console.log("--------------------iteration no. ", i, "at", time);
try {
// número aleatório
const nbr = milli % 2;
if (nbr === 0) {
// lança uma mensagem de erro
throw "error";
}
// se chegamos aqui, significa que não houve erro
console.log("no error");
} catch (error) {
// se chegamos aqui, significa que houve um erro
console.log("error1=", error);
} finally {
// executado em todos os casos, com erro ou não
console.log("finally")
}
}
|
- linha 4: import moment from 'moment' — importa uma biblioteca de terceiros, assim como sprintf-js no capítulo “Strings”;
- a cada iteração do laço, se o número atual de milissegundos for par, um erro é lançado (linha 21) e capturado pelo bloco
catch; caso contrário, a mensagem “no error” é exibida;
- A cláusula [finally] é executada sistematicamente, quer tenha ocorrido um erro ou não.
Este script depende do instante exato da execução: o resultado abaixo (obtido em uma execução real) será diferente a cada execução—somente o princípio (o bloco finally é sempre executado) é garantido:
npx tsx exceptions/excep-01.ts
Resultado da execução:
| --------------------iteration no. 0 at 07:40:11:070
error1= error
finally
--------------------iteration no. 1 at 07:40:11:076
error1= error
finally
--------------------iteration no. 2 at 07:40:11:076
error1= error
finally
--------------------iteration no. 3 at 07:40:11:077
no error
finally
--------------------iteration no. 4 at 07:40:11:077
no error
finally
--------------------iteration no. 5 at 07:40:11:077
no error
finally
--------------------iteration no. 6 at 07:40:11:077
no error
finally
--------------------iteration no. 7 at 07:40:11:077
no error
finally
--------------------iteration no. 8 at 07:40:11:077
no error
finally
--------------------iteration no. 9 at 07:40:11:077
no error
finally
|
3.7.2. Script [excep-02]
Este script demonstra que [throw] pode lançar qualquer tipo de dado—string, array, objeto ou instância de Error—e que esse dado é integralmente capturado pela cláusula catch:
| 'use strict';
// podemos "lançar" praticamente qualquer coisa para sinalizar um erro
let i = 0;
console.log("--------------------attempt no. ", i);
// lança uma string
try {
throw "error msg";
} catch (error) {
// houve um erro
console.log("error=[", error, "], type=", typeof (error));
}
// lança um objeto literal
i++;
console.log("--------------------attempt no. ", i);
try {
throw [1, 2, 3]
} catch (error) {
// houve um erro
console.log("error=[", error, "], type=", typeof (error));
}
// lança um objeto
i++;
console.log("--------------------attempt no. ", i);
try {
throw { name: "hercule", country: "ancient greece" }
} catch (error) {
// houve um erro
console.log("error=[", error, "], type=", typeof (error));
}
// lança um tipo Error
i++;
console.log("--------------------attempt no. ", i);
try {
throw new Error("network connection error");
} catch (error) {
// houve um erro
console.log("error=[", error, "], type=", typeof (error));
}
// lança um tipo Error
i++;
console.log("--------------------attempt no. ", i);
try {
throw new Error("network connection error");
} catch (error: any) {
// houve um erro - a mensagem está em [error.message]
// [any] porque o TypeScript tipa as variáveis de catch como [unknown] por padrão (veja os outros
// blocos try/catch acima, nos quais basta exibir [error] sem acessar uma propriedade)
console.log("error.message=[", error.message, "], type(error)=", typeof (error));
}
|
- [Error] é uma classe nativa cujo construtor aceita uma mensagem de erro como primeiro parâmetro, que pode ser recuperada em error.message;
- O TypeScript define por padrão a variável do catch como "unknown" (veja a nota na linha 47): acessar uma propriedade como .message exige então uma verificação de tipo (instanceof, veja o script seguinte) ou uma anotação explícita no catch (error: any) como mostrado aqui na linha 47;
- Existem outras classes além de
Error que podem ser usadas para sinalizar um erro: EvalError, RangeError, ReferenceError, SyntaxError, TypeError, URIError.
npx tsx exceptions/excep-02.ts
Resultado da execução:
| --------------------attempt no. 0
error=[ error msg ], type= string
--------------------attempt no. 1
error=[ [ 1, 2, 3 ] ], type= object
--------------------attempt no. 2
error=[ { name: 'hercule', country: 'ancient greece' } ], type= object
--------------------attempt no. 3
error=[ Error: network connection error
at exceptions/excep-02.ts:35:9 ], type= object
--------------------attempt no. 4
error.message=[ network connection error ], type(error)= object
|
3.7.3. Script [excep-03]
Este script demonstra como distinguir, dentro de um bloco catch, o tipo específico do erro capturado, usando o operador [instanceof]:
| 'use strict';
// pacote moment
import moment from 'moment';
// diferenciação da instância de Error recebida em um [catch]
for (let i = 0; i < 10; i++) {
// data - hora do momento atual
const now = Date.now();
// formatação da hora para obter os milissegundos
const time = moment(now).format("HH:mm:ss:SSS");
// os milissegundos
const milli = Number(time.substr(time.length - 3));
console.log("--------------------iteration no. ", i);
try {
// número aleatório
const nbr = milli % 3;
switch (nbr) {
case 0:
throw new ReferenceError("error 1");
case 1:
throw new RangeError("error 2");
default:
throw new EvalError("error 3");
}
} catch (error) {
// houve um erro
if (error instanceof ReferenceError) {
console.log("ReferenceError :", error.message);
} else {
if (error instanceof RangeError) {
console.log("RangeError :", error.message);
}
else {
if (error instanceof EvalError) {
console.log("EvalError :", error.message);
}
}
}
}
}
|
Mais uma vez, o resultado depende do instante exato da execução—cada execução produz uma distribuição diferente entre os três tipos de erro:
npx tsx exceptions/excep-03.ts
Resultado da execução:
| --------------------iteration no. 0
RangeError : error 2
--------------------iteration no. 1
ReferenceError : error 1
--------------------iteration no. 2
ReferenceError : error 1
--------------------iteration no. 3
ReferenceError : error 1
--------------------iteration no. 4
RangeError : error 2
--------------------iteration no. 5
RangeError : error 2
--------------------iteration no. 6
RangeError : error 2
--------------------iteration no. 7
EvalError : error 3
--------------------iteration no. 8
EvalError : error 3
--------------------iteration no. 9
EvalError : error 3
|
3.7.4. Script [excep-04]
[NOVO desde 2019] Este script inclui duas adições importantes introduzidas com o ECMAScript 2022: a opção [cause] de Error e as classes de erro personalizadas.
| 'use strict';
// ========================================================================
// [NOVO desde 2019] a propriedade [cause] de um erro (ECMAScript 2022)
// ========================================================================
// é comum capturar um erro técnico (de baixo nível) e
// relançá-lo como um erro mais explícito (de alto nível), para que
// o código chamador entenda melhor o contexto de negócio.
// ANTES de 2022, perdíamos o rastro do erro original ao fazer isso.
function readConfiguration(): void {
// simula um erro técnico de baixo nível (ex.: arquivo não encontrado)
throw new Error("ENOENT: file 'config.json' not found");
}
function startApplication(): void {
try {
readConfiguration();
} catch (technicalError) {
// o 2º parâmetro { cause } permite anexar o erro original
// ao novo erro, sem perder a informação
throw new Error("unable to start the application", { cause: technicalError });
}
}
try {
startApplication();
} catch (error: any) {
console.log("error=", error.message);
// error.cause dá acesso ao erro original, muito útil para depuração
console.log("cause=", error.cause?.message);
}
// ------------------------------------------------------------------------
// classes de erro personalizadas (já possíveis desde o ECMAScript 2015,
// mas muito frequentemente usadas com [cause] desde 2022, daí a revisão aqui)
// ------------------------------------------------------------------------
// podemos criar nossos próprios tipos de erro estendendo [Error], o que permite então
// distingui-los com [instanceof], como para ReferenceError ou RangeError
// (cf. exceptions/excep-03.js)
class ValidationError extends Error {
fieldInError: string;
constructor(message: string, fieldInError: string, options?: ErrorOptions) {
// passamos a mensagem e as [options] (incluindo uma eventual cause) ao [Error] pai
super(message, options);
// o nome padrão seria "Error"; nós o personalizamos
this.name = "ValidationError";
// podemos adicionar informações de negócio específicas a este tipo de erro
this.fieldInError = fieldInError;
}
}
function validate(age: unknown): boolean {
if (typeof (age) !== "number") {
throw new ValidationError("the age must be a number", "age");
}
if (age < 0 || age > 130) {
throw new ValidationError("the age must be between 0 and 130", "age");
}
return true;
}
// algumas tentativas com valores diferentes
for (const value of [25, -5, "thirty", 200]) {
try {
validate(value);
console.log(`value [${value}] : validation OK`);
} catch (error) {
// podemos distinguir nossos erros de negócio dos demais erros graças a instanceof
if (error instanceof ValidationError) {
console.log(`value [${value}] : validation error on [${error.fieldInError}] - ${error.message}`);
} else {
// um erro inesperado, não previsto pelo nosso código
throw error;
}
}
}
|
- linhas 17–22: ao capturar um erro técnico de baixo nível para relançá-lo de forma mais explícita, o segundo parâmetro {cause} de
new Error(...) permite preservar o rastro do erro original, que de outra forma se perderia (comportamento anterior a 2022);
- linha 31: error.cause?.message recupera a mensagem do erro original, o que é muito útil para depuração;
- linhas 41–53: uma classe de erro personalizada (ValidationError extends Error) permite criar seus próprios tipos de erro de negócio, que podem então ser distinguidos com
instanceof (linha 72), assim como ReferenceError ou RangeError no script anterior.
npx tsx exceptions/excep-04.ts
Resultado da execução:
| error= unable to start the application
cause= ENOENT: file 'config.json' not found
value [25] : validation OK
value [-5] : validation error on [age] - the age must be between 0 and 130
value [thirty] : validation error on [age] - the age must be a number
value [200] : validation error on [age] - the age must be between 0 and 130
|
3.8. Módulos
Os módulos ECMAScript permitem construir aplicações estruturadas em arquivos independentes e reutilizáveis, cada um exportando o que deseja disponibilizar aos outros. Os scripts deste capítulo estão na pasta [modules] do projeto.

3.8.1. Scripts [import-01, export-01]
O script [import-01] usa o módulo [export-01]:
| // export default de um objeto sem nome
export default {
data: 2,
do() {
console.log(this.data);
}
};
|
- [export default] exporta um objeto sem nome—só é permitida uma exportação default por módulo.
| 'use strict';
// importação de um objeto exportado por padrão
import export01 from './export-01.js';
// uso desse objeto
export01.do();
// um export default pode ser importado com qualquer nome
import data from './export-01.js';
console.log(data.data);
|
- As linhas 3 e 7 importam a exportação default do módulo com dois nomes diferentes (export01 e depois data)—o nome dado à importação é arbitrário; não precisa corresponder a nada no módulo de origem;
- Depois de importado, o objeto pode ser usado como se tivesse sido definido localmente.
npx tsx modules/import-01.ts
Resultado da execução:
3.8.2. Scripts [import-02, export-02]
Estes scripts mostram que exportar um objeto nomeado (armazenado antes em uma variável) funciona exatamente da mesma maneira:
| // export default de um objeto nomeado
const data = {
data: 2,
do() {
console.log(this.data);
}
};
// export
export default data;
|
| 'use strict';
// importação de um objeto exportado por padrão
import module1 from './export-02.js';
// uso desse objeto
module1.do();
// um export default pode ser importado com qualquer nome
import module2 from './export-02.js';
console.log(module2.data);
|
npx tsx modules/import-02.ts
Resultado da execução:
3.8.3. Scripts [import-03, export-03]
Um módulo pode exportar vários elementos com a sintaxe export { element }:
| // exports múltiplos
// export de objeto
const data = {
data: 2,
do() {
console.log(this.data);
}
};
// export de função
export { data };
function doSomething(): void {
console.log("doSomething");
}
export { doSomething };
|
| 'use strict';
// importação de um módulo [export03]
import {data, doSomething} from './export-03.js';
// uso das importações
data.do();
doSomething();
// outra sintaxe
import * as module from './export-03.js';
// uso da importação
console.log(module.data);
module.doSomething();
|
- Linha 3: as importações nomeadas usam os nomes exatos dos elementos exportados, entre chaves;
- linha 8:
import \* as module from '...' importa todos os elementos exportados, agrupados em um objeto nomeado (aqui, module).
npx tsx modules/import-03.ts
Resultado da execução:
| 2
doSomething
{ data: 2, do: [Function: do] }
doSomething
|
3.8.4. Scripts [import-04, remote-config] — await no nível superior
[NOVO desde 2019] A versão 2022 do ECMAScript introduziu o await no nível superior: a possibilidade de usar await diretamente no nível superior de um módulo, sem envolvê-lo em uma função async . Antes, era preciso criar uma função “main” async e chamá-la imediatamente (veja o próximo capítulo, script async-06).
O módulo [remote-config] simula o carregamento de uma configuração remota e usa await no nível superior:
| // módulo que simula a leitura de uma configuração remota (ex.: chamada de rede)
// usado por modules/import-04.js para ilustrar o top-level await
interface Configuration {
applicationName: string;
version: string;
}
// uma função que simula uma chamada assíncrona (ex.: fetch de um arquivo de configuração)
function loadFromNetwork(): Promise<Configuration> {
return new Promise(resolve => {
setTimeout(() => {
resolve({ applicationName: "ECMAScript course", version: "2026" });
}, 300);
});
}
// [NOVO desde 2022] top-level await: podemos usar [await] diretamente
// no nível superior de um módulo, sem envolvê-lo em uma função async.
// o módulo INTEIRO (e qualquer módulo que o importe) espera esta linha terminar
// antes de continuar: isso é muito prático para inicializar uma configuração
// uma única vez, quando o módulo é carregado.
console.log("[remote-config] loading the configuration...");
const configuration: Configuration = await loadFromNetwork();
console.log("[remote-config] configuration loaded");
// exportamos o resultado, já resolvido (e não uma promise a ser aguardada de novo)
export default configuration;
|
O script [import-04] importa esse módulo:
| 'use strict';
// ========================================================================
// [NOVO desde 2019] top-level await (ECMAScript 2022)
// ========================================================================
// antes do ECMAScript 2022, era impossível usar [await] fora de
// uma função [async]: no nível superior de um script, era preciso criar
// uma função "main" async e chamá-la imediatamente (cf. async/async-06.js)
// nota sobre a ordem de execução: com módulos ES, os [import]s são sempre
// avaliados ANTES do código do módulo que importa, mesmo que escritos na 1ª linha.
// é por isso que os logs de [remote-config.js] são exibidos antes deste,
// embora a linha seguinte esteja textualmente colocada antes do import neste arquivo.
console.log("[import-04] before importing the remote-config module");
// graças ao top-level await usado EM remote-config.js, o import abaixo
// só termina quando a configuração acaba de ser carregada: não é preciso
// chamar .then() nem criar uma função async aqui
import configuration from './remote-config.js';
console.log("[import-04] after the import: the configuration is already available");
console.log("configuration =", configuration);
// também podemos usar [await] diretamente aqui, neste módulo, no nível superior
console.log("[import-04] waiting 200ms with top-level await...");
await new Promise(resolve => setTimeout(resolve, 200));
console.log("[import-04] finished");
|
- Linha 19: graças ao
await de nível superior usado **em **remote-config.ts, a importação da linha 19 só termina depois que a configuração termina de ser carregada—não há necessidade de .then() nem de uma função async aqui;
- Os módulos ES são sempre avaliados antes do código do módulo que os importa, mesmo que a instrução import não esteja na primeira linha do arquivo: é por isso que as mensagens de remote-config.ts são exibidas antes das de import-04.ts, embora estas últimas estejam literalmente colocadas antes da importação no arquivo;
- linha 26: também é possível usar
await diretamente dentro de import-04.ts , em seu próprio nível superior.
npx tsx modules/import-04.ts
Resultado da execução:
| [remote-config] loading the configuration...
[remote-config] configuration loaded
[import-04] before importing the remote-config module
[import-04] after the import: the configuration is already available
configuration = { applicationName: 'ECMAScript course', version: '2026' }
[import-04] waiting 200ms with top-level await...
[import-04] finished
|
3.9. Programação orientada a eventos e funções assíncronas
Uma função assíncrona é uma função cuja execução é iniciada, mas cujo resultado não é aguardado imediatamente. Quando a execução termina, a função assíncrona sinaliza seu resultado—por meio de um evento ou de uma **[Promise]**, como veremos adiante.
Esse modo de funcionamento é adequado à execução em um navegador, onde a aplicação responde constantemente a eventos (cliques, teclas digitadas, respostas de rede etc.). Os scripts deste capítulo são executados pelo [node.js], que também usa um loop de eventos:
- a execução do código principal do script é o primeiro evento processado;
- se esse código iniciou tarefas assíncronas, a execução do script continua até que elas terminem—elas emitem um evento ao concluir, que é colocado na fila do loop de eventos;
- o script principal deve se inscrever nesses eventos para recuperar seus resultados;
- o script só termina quando todos os eventos que ele emitiu tiverem sido processados.
Os scripts deste capítulo estão na pasta [async] do projeto.

3.9.1. Script [async-01]
Este script demonstra o comportamento de um script que contém uma ação assíncrona, usando a função nativa [setTimeout]:
| 'use strict';
// importações
import moment from 'moment';
import { sprintf } from 'sprintf-js';
// início
const scriptStart = moment(Date.now());
console.log("[start of the script],", time());
// setTimeout arma um temporizador de 1000 ms (2º parâmetro) e retorna imediatamente o número desse temporizador
// quando o temporizador esgota os 1000 ms, emite um evento que é colocado na fila do runtime
// quando o evento é processado pelo runtime, a função (1º parâmetro) é executada
setTimeout(function () {
// este código será executado quando o temporizador chegar ao valor 0
console.log("[end of the asynchronous action setTimeout],", time(scriptStart));
}, 1000)
// será exibido antes da msg da função interna do temporizador
console.log("[end of the main code of the script],", time(scriptStart));
// utilitário que exibe a hora e a duração
function time(start?: moment.Moment): string {
// hora do momento atual
const now = moment(Date.now());
// formatação da hora
let result = "time=" + now.format("HH:mm:ss:SSS");
// deve-se calcular uma duração?
if (start) {
const duration = now.valueOf() - start.valueOf();
const milliseconds = duration % 1000;
const seconds = Math.floor(duration / 1000);
// formatação da hora + duração
result = result + sprintf(", duration= %s second(s) and %s milliseconds", seconds, milliseconds);
}
// resultado
return result;
}
|
- Linhas 14–17: [setTimeout] recebe dois parâmetros: uma função a executar e um atraso em milissegundos. Ele é executado instantaneamente: inicia um temporizador e devolve o controle imediatamente, sem esperar o atraso transcorrer;
- linha 20: portanto, essa mensagem aparece antes da mensagem da linha 16, embora esteja escrita depois no código;
- linha 23: function time(start?: moment.Moment): string — o parâmetro start é opcional (?), do tipo moment.Moment; se fornecido, a função calcula e acrescenta o tempo decorrido.
npx tsx async/async-01.ts
Resultado da execução:
| [start of the script], time=07:41:36:456
[end of the main code of the script], time=07:41:36:457, duration= 0 second(s) and 2 milliseconds
[end of the asynchronous action setTimeout], time=07:41:37:458, duration= 1 second(s) and 3 milliseconds
|
Vemos que a ação assíncrona setTimeout termina cerca de 1 segundo depois do fim do código principal—que é exatamente o atraso programado. O script como um todo, porém, só termina quando essa tarefa assíncrona é concluída.
Nota: usaremos setTimeout para simular tarefas assíncronas ao longo deste capítulo. Uma tarefa assíncrona real (requisição de rede, leitura de arquivo etc.) se comporta da mesma forma: devolve o controle imediatamente e informa o resultado mais tarde—em geral por meio de dois eventos possíveis, um de sucesso e outro de falha.
3.9.2. Script [async-02]
Este script demonstra como uma função assíncrona pode comunicar seu resultado emitindo eventos, usando a classe nativa EventEmitter (módulo node:events):
| 'use strict';
// funções assíncronas podem retornar um resultado emitindo um evento
// o código principal pode recuperar esses resultados assinando os eventos emitidos
// importações
import moment from 'moment';
import { sprintf } from 'sprintf-js';
import EventEmitter from 'events';
// início
const scriptStart = moment(Date.now());
console.log("[start of the script],", time());
// um emissor de eventos
const eventEmitter = new EventEmitter();
// setTimeout arma um temporizador de 1000 ms (2º parâmetro) e retorna imediatamente o número desse temporizador
// quando o temporizador esgota os 1000 ms, emite um evento que é colocado na fila do runtime
// quando o evento é processado pelo runtime, a função (1º parâmetro) é executada
setTimeout(function () {
// este código será executado quando o temporizador chegar ao valor 0
console.log("[setTimeout, end of the 1 s timer],", time(scriptStart));
// emitimos um evento para dizer que um resultado está disponível
eventEmitter.emit("timer1Success", { success: 4 });
// emitimos outro evento para dizer que outro resultado está disponível
eventEmitter.emit("timer1Failure", { failure: 6 });
}, 1000)
// assinamos o evt [timer1Success]
eventEmitter.on('timer1Success', (result) => {
console.log(sprintf("the timer's asynchronous function returned the result [%j], %s, via the [timer1Success] event", result, time(scriptStart)));
});
// assinamos o evt [timer1Failure]
eventEmitter.on('timer1Failure', (result) => {
console.log(sprintf("the timer's asynchronous function returned the result [%j], %s, via the [timer1Failure] event", result, time(scriptStart)));
});
// será exibido antes das msgs dos evts emitidos pela função associada a [timer1]
console.log("[end of the main code of the script],", time(scriptStart));
// utilitário que exibe a hora e a duração
function time(start?: moment.Moment): string {
// hora do momento atual
const now = moment(Date.now());
// formatação da hora
let result = "time=" + now.format("HH:mm:ss:SSS");
// deve-se calcular uma duração?
if (start) {
const duration = now.valueOf() - start.valueOf();
const milliseconds = duration % 1000;
const seconds = Math.floor(duration / 1000);
// formatação da hora + duração
result = result + sprintf(", duration= %s second(s) and %s milliseconds", seconds, milliseconds);
}
// resultado
return result;
}
|
- linha 9: import EventEmitter from 'events' — importa a classe que permite emitir e escutar eventos;
- linha 15: const eventEmitter = new EventEmitter() — um emissor de eventos é instanciado com
new;
- linhas 24 e 26: a função encapsulada em setTimeout emite dois eventos, timer1Success e timer1Failure, cada um com seus próprios dados associados (aqui, apenas para fins de demonstração—normalmente, uma única tarefa emitiria apenas um ou outro);
- linhas 29–37: o código principal se inscreve nesses dois eventos com eventEmitter.on(eventName, callback)—o callback só será executado quando o evento for de fato emitido, e não no momento da inscrição;
- linha 40: o código principal termina aqui, mas o script global só termina quando a tarefa assíncrona (e os callbacks inscritos) terminarem de ser executados.
npx tsx async/async-02.ts
Resultado da execução:
| [start of the script], time=07:41:38:163
[end of the main code of the script], time=07:41:38:170, duration= 0 second(s) and 7 milliseconds
[setTimeout, end of the 1 s timer], time=07:41:39:173, duration= 1 second(s) and 10 milliseconds
the timer's asynchronous function returned the result [{"success":4}], time=07:41:39:173, duration= 1 second(s) and 10 milliseconds, via the [timer1Success] event
the timer's asynchronous function returned the result [{"failure":6}], time=07:41:39:173, duration= 1 second(s) and 10 milliseconds, via the [timer1Failure] event
|
3.9.3. Script [async-03]
O loop de eventos do node.js executa apenas um evento por vez: o evento seguinte só é processado depois que o anterior termina. Um código síncrono que mantém o processador ocupado por muito tempo atrasa, portanto, o processamento de todos os eventos pendentes—inclusive os que já foram emitidos. Este script (idêntico ao async-02, com um laço intensivo acrescentado) demonstra isso:
| 'use strict';
// funções assíncronas podem retornar um resultado emitindo um evento
// o código principal pode recuperar esses resultados assinando os eventos emitidos
// importações
import moment from 'moment';
import { sprintf } from 'sprintf-js';
import EventEmitter from 'events';
// início
const scriptStart = moment(Date.now());
console.log("[start of the script],", time());
// um emissor de eventos
const eventEmitter = new EventEmitter();
// setTimeout arma um temporizador de 1000 ms (2º parâmetro) e retorna imediatamente o número desse temporizador
// quando o temporizador esgota os 1000 ms, emite um evento que é colocado na fila do runtime
// quando o evento é processado pelo runtime, a função (1º parâmetro) é executada
setTimeout(function () {
// este código será executado quando o temporizador chegar ao valor 0
console.log("[setTimeout, end of the 1 s timer],", time(scriptStart));
// emitimos um evento para dizer que um resultado está disponível
eventEmitter.emit("timer1Success", { success: 4 });
// emitimos outro evento para dizer que outro resultado está disponível
eventEmitter.emit("timer1Failure", { failure: 6 });
}, 1000)
// assinamos o evt [timer1Success]
eventEmitter.on('timer1Success', (result) => {
console.log(sprintf("the timer's asynchronous function returned the result [%j], %s, via the [timer1Success] event", result, time(scriptStart)));
});
// assinamos o evt [timer1Failure]
eventEmitter.on('timer1Failure', (result) => {
console.log(sprintf("the timer's asynchronous function returned the result [%j], %s, via the [timer1Failure] event", result, time(scriptStart)));
});
// código síncrono um pouco intensivo que impediu o código principal de terminar antes do fim de [timer1]
for (let i = 0; i < 1000000; i++) {
for (let j = 0; j < 10000; j++) {
i + i ^ 2 + i ^ 3;
}
}
// será exibido antes das msgs dos evts emitidos pela função associada a [timer1]
console.log("[end of the main code of the script],", time(scriptStart));
// utilitário que exibe a hora e a duração
function time(start?: moment.Moment): string {
// hora do momento atual
const now = moment(Date.now());
// formatação da hora
let result = "time=" + now.format("HH:mm:ss:SSS");
// deve-se calcular uma duração?
if (start) {
const duration = now.valueOf() - start.valueOf();
const milliseconds = duration % 1000;
const seconds = Math.floor(duration / 1000);
// formatação da hora + duração
result = result + sprintf(", duration= %s second(s) and %s milliseconds", seconds, milliseconds);
}
// resultado
return result;
}
|
- linhas 40–44: um laço duplo puramente síncrono, sem relação com a tarefa assíncrona, mas que ocupa o processador por vários segundos;
- o temporizador de 1 segundo terminou sua contagem regressiva bem antes do fim desse laço—mas o evento que ele emitiu precisa esperar que o código síncrono devolva o controle ao loop de eventos para poder, enfim, ser processado.
npx tsx async/async-03.ts
Resultado da execução:
| [start of the script], time=07:41:39:891
[end of the main code of the script], time=07:41:45:623, duration= 5 second(s) and 732 milliseconds
[setTimeout, end of the 1 s timer], time=07:41:45:625, duration= 5 second(s) and 734 milliseconds
the timer's asynchronous function returned the result [{"success":4}], time=07:41:45:625, duration= 5 second(s) and 734 milliseconds, via the [timer1Success] event
the timer's asynchronous function returned the result [{"failure":6}], time=07:41:45:625, duration= 5 second(s) and 734 milliseconds, via the [timer1Failure] event
|
O código principal levou cerca de 5,7 segundos para ser executado (a duração varia conforme a máquina), embora o temporizador já tivesse terminado havia muito tempo sua contagem de um segundo: o evento associado teve de esperar o fim do laço síncrono. É importante observar que um código síncrono de longa duração deve, sempre que possível, ser dividido em tarefas assíncronas mais curtas.
3.9.4. O mecanismo de Promise
O tipo [Promise] é uma classe que evita gerenciar eventos explicitamente: isso é feito de forma implícita, mas entender os eventos subjacentes ajuda a compreender melhor seu funcionamento. Seu construtor recebe como parâmetro uma função assíncrona, à qual passa duas funções, tradicionalmente chamadas [resolve] e [reject]:
const promise = new Promise(function (resolve, reject) {
// uma tarefa assíncrona é iniciada
// ...
// em caso de sucesso: chamar resolve(result), em que [result] é o resultado da tarefa
// em caso de falha: chamar reject(error), em que [error] encapsula o erro encontrado
});
Um objeto Promise pode estar em um de quatro estados:
- [pending]: a tarefa assíncrona ainda não terminou;
- [fulfilled]: ela terminou com sucesso;
- [rejected]: ela falhou;
- [settled]: ela terminou (independentemente de ter tido sucesso ou falhado).
Você se inscreve nos resultados de uma Promise com a sintaxe promise.then(f1).catch(f2).finally(f3): f1 é executada em caso de sucesso (recebe o resultado passado por resolve), f2 é executada em caso de falha (recebe o erro devolvido por reject) e f3 é executada em todos os casos, sem nenhum parâmetro.
3.9.5. Script [async-04]
Este script cria duas Promises independentes, cada uma encapsulando um setTimeout, e se inscreve em seus resultados:
| 'use strict';
// é possível obter os resultados (sucesso, falha) de uma função assíncrona
// sem usar eventos explicitamente, graças à classe [Promise]
// essa classe usa eventos implicitamente, mas eles não são visíveis no código
// importações
import moment from 'moment';
import { sprintf } from 'sprintf-js';
// início
const scriptStart = moment(Date.now());
console.log("[start of the script],", time(scriptStart));
// definição de uma tarefa assíncrona usando uma [Promise]
// a tarefa assíncrona é o parâmetro do construtor de [Promise]
const promise1Start = moment(Date.now());
const promise1 = new Promise<string>(function (resolve) {
// log
console.log("[start of the asynchronous function of promise1],", time(promise1Start));
// código assíncrono
setTimeout(function () {
// este código é executado após um atraso de 1 segundo (2º parâmetro)
console.log("[end of the asynchronous function of promise1],", time(promise1Start));
// a tarefa assíncrona retorna um resultado com a função [resolve]
// a promise é então bem-sucedida
resolve('[success]');
}, 1000)
});
// podemos conhecer o resultado da promise [promise1]
// quando ela foi resolvida (resolve) ou rejeitada (reject)
// a instrução seguinte é uma assinatura do evt [resolved] por meio do método [then]
// e do evt [rejected] por meio do método [catch]
// o método [finally] é executado tanto após um then quanto após um catch
promise1.then(result => {
// caso em que a promise é bem-sucedida [evt resolved]
console.log(sprintf("[promise1.then], %s, result=%s", time(promise1Start), result));
}).catch(result => {
// caso de erro [evt rejected]
console.log(sprintf("[promise1.catch], %s, result=%s", time(promise1Start), result));
}).finally(() => {
// executado em todos os casos
console.log("[promise1.finally]", time(promise1Start));
});
// definição de uma tarefa assíncrona usando uma [Promise]
const promise2Start = moment(Date.now());
const promise2 = new Promise<string>(function (resolve, reject) {
// log
console.log("[start of the asynchronous function of promise2],", time(promise2Start));
// tarefa assíncrona
setTimeout(function () {
console.log("[end of the asynchronous function of promise2],", time(promise2Start));
// a tarefa assíncrona retorna um resultado com a função [reject]
// a promise então falhou
reject('[failure]');
}, 2000)
});
// podemos conhecer o resultado da promise [promise2]
// quando ela foi resolvida (resolve) ou rejeitada (reject)
promise2.then(result => {
// caso em que a promise é bem-sucedida [evt resolved]
console.log(sprintf("[promise2.then], %s, result=%s", time(promise2Start), result));
}).catch(result => {
// caso de erro [evt rejected]
console.log(sprintf("[promise2.catch], %s, result=%s", time(promise2Start), result));
}).finally(() => {
// executado em todos os casos
console.log(sprintf("[promise2.finally], %s", time(promise2Start)));
});
// será exibido antes das msgs das funções assíncronas e dos evts associados
console.log("[end of the main code of the script],", time(scriptStart));
// utilitário
function time(start?: moment.Moment): string {
// hora do momento atual
const now = moment(Date.now());
// formatação da hora
let result = "time=" + now.format("HH:mm:ss:SSS");
if (start) {
const duration = now.valueOf() - start.valueOf();
const milliseconds = duration % 1000;
const seconds = Math.floor(duration / 1000);
// formatação da duração
result = result + sprintf(", duration= %s second(s) and %s milliseconds", seconds, milliseconds);
}
// resultado
return result;
}
|
- linha 18: new Promise<string>(function (resolve) {...}) — o TypeScript permite especificar, por meio do parâmetro genérico <string>, o tipo do valor que
resolve retornará; sem ele, o tipo seria inferido como unknown;
- promise1 é resolvida com sucesso após 1 segundo (resolve('[success]')); promise2 falha após 2 segundos (reject('[failure]'));
- o código principal (linha 75) termina bem antes de as duas promises terem um resultado—o script global, porém, continua até que ambas estejam settled.
npx tsx async/async-04.ts
Resultado da execução:
| [start of the script], time=07:42:29:437, duration= 0 second(s) and 0 milliseconds
[start of the asynchronous function of promise1], time=07:42:29:443, duration= 0 second(s) and 0 milliseconds
[start of the asynchronous function of promise2], time=07:42:29:444, duration= 0 second(s) and 0 milliseconds
[end of the main code of the script], time=07:42:29:444, duration= 0 second(s) and 7 milliseconds
[end of the asynchronous function of promise1], time=07:42:30:445, duration= 1 second(s) and 2 milliseconds
[promise1.then], time=07:42:30:446, duration= 1 second(s) and 3 milliseconds, result=[success]
[promise1.finally] time=07:42:30:447, duration= 1 second(s) and 4 milliseconds
[end of the asynchronous function of promise2], time=07:42:31:445, duration= 2 second(s) and 1 milliseconds
[promise2.catch], time=07:42:31:446, duration= 2 second(s) and 2 milliseconds, result=[failure]
[promise2.finally], time=07:42:31:446, duration= 2 second(s) and 2 milliseconds
|
3.9.6. Script [async-05]
O mais comum é definir uma função assíncrona que retorna uma Promise, em vez de criar diretamente o objeto Promise—o que é útil quando a função precisa de parâmetros. Este script define duas funções assíncronas e espera que ambas terminem com [Promise.all]:
| 'use strict';
// podemos definir funções assíncronas que retornam um tipo [Promise]
// elas podem então ser marcadas com a palavra-chave [async]
// aqui de novo
// importações
import moment from 'moment';
import { sprintf } from 'sprintf-js';
// início
const scriptStart = moment(Date.now());
console.log("[start of the script],", time());
// forma do resultado retornado por async01 e async02
interface AsyncResult {
prop1: number[];
prop2: string;
prop3: number;
}
// uma função assíncrona pode retornar uma [Promise]
// e ter então o atributo [async]
async function async01(p1: number): Promise<AsyncResult> {
return new Promise<AsyncResult>(resolve => {
console.log("[start of the asynchronous task async01]");
// a tarefa assíncrona
const async01Start = moment(Date.now());
setTimeout(function () {
// este código é executado após um atraso de 1 segundo (2º parâmetro)
console.log("[end of the asynchronous task async01],", time(async01Start));
// a tarefa assíncrona pode retornar um resultado complexo
resolve({
prop1: [10, 20, 30],
prop2: "abcd",
prop3: p1,
});
}, 1000)
});
}
// uma função pode retornar uma [Promise]
// e pode ter então o atributo [async]
async function async02(p1: number, p2: number): Promise<AsyncResult> {
return new Promise<AsyncResult>(resolve => {
console.log("[start of the asynchronous task async02]");
// tarefa assíncrona
const async02Start = moment(Date.now());
setTimeout(function () {
// o código a seguir é executado após um atraso de 2 segundos (2º parâmetro)
console.log("[end of the asynchronous task async02],", time(async02Start));
// a tarefa assíncrona pode retornar um resultado complexo
resolve({
prop1: [11, 21, 31],
prop2: "xyzt",
prop3: p1 + p2
});
}, 2000)
})
}
// lançamos as duas funções assíncronas em paralelo
// e esperamos que ambas terminem
// o then só será executado se as duas funções tiverem emitido o evt [resolved]
// o catch será executado assim que uma das duas funções emitir o evt [rejected]
Promise.all([async01(10), async02(10, 20)])
// o resultado é um array [result1, result2], em que [result1] é o resultado emitido por um [resolve] de [async01]
// e [result2] o resultado emitido por um [resolve] de [async02]
.then(result => {
console.log(sprintf("[promise-all success], %s, result=%j", time(scriptStart), result));
})
// error é o resultado emitido pelo primeiro [reject] de uma das duas funções assíncronas
.catch(error => {
console.log(sprintf("[promise-all error], %s, error=%j", time(scriptStart), error));
})
// finally é executado após o then ou o catch
.finally(() => {
console.log(sprintf("[promise-all finally], %s", time(scriptStart)));
});
// será exibido antes das msgs das funções assíncronas e dos evts associados
console.log("[end of the main code of the script],", time(scriptStart));
// utilitário
function time(start?: moment.Moment): string {
// hora do momento atual
const now = moment(Date.now());
// formatação da hora
let result = "time=" + now.format("HH:mm:ss:SSS");
if (start) {
const duration = now.valueOf() - start.valueOf();
const milliseconds = duration % 1000;
const seconds = Math.floor(duration / 1000);
// formatação da duração
result = result + sprintf(", duration= %s second(s) and %s milliseconds", seconds, milliseconds);
}
// resultado
return result;
}
|
- linhas 23 e 43: as funções assíncronas são tipadas como Promise<AsyncResult> graças à interface AsyncResult definida acima;
- linha 65: [Promise.all([...])] espera que todas as promises do array sejam resolvidas antes de executar seu
then—assim que uma falha, seu catch é executado imediatamente, sem esperar pelas outras;
- as duas tarefas são executadas em paralelo (seus respectivos tempos de espera se sobrepõem): a duração total (~2s) corresponde à da mais longa das duas, e não à sua soma (~3s).
npx tsx async/async-05.ts
Resultado da execução:
| [start of the script], time=07:42:32:179
[start of the asynchronous task async01]
[start of the asynchronous task async02]
[end of the main code of the script], time=07:42:32:180, duration= 0 second(s) and 6 milliseconds
[end of the asynchronous task async01], time=07:42:33:181, duration= 1 second(s) and 1 milliseconds
[end of the asynchronous task async02], time=07:42:34:182, duration= 2 second(s) and 2 milliseconds
[promise-all success], time=07:42:34:183, duration= 2 second(s) and 9 milliseconds, result=[{"prop1":[10,20,30],"prop2":"abcd","prop3":10},{"prop1":[11,21,31],"prop2":"xyzt","prop3":30}]
[promise-all finally], time=07:42:34:183, duration= 2 second(s) and 9 milliseconds
|
3.9.7. Script [async-06] — async / await
As palavras-chave [async]/[await] permitem escrever código assíncrono que se parece com código síncrono: o tratamento de eventos subjacente fica totalmente oculto, o que torna o código muito mais fácil de ler. Este script define três funções assíncronas—a terceira falha intencionalmente—e as executa primeiro de forma sequencial e depois em paralelo:
| 'use strict';
// execução paralela ou sequencial de várias tarefas assíncronas
// com as palavras-chave async / await
// importações
import moment from 'moment';
import { sprintf } from 'sprintf-js';
// início
const scriptStart = moment(Date.now());
console.log("[start of the main code of the script],", time());
// forma do resultado retornado por async01/async02/async03
interface AsyncResult {
prop1: number[];
prop2: string;
}
// uma função assíncrona que retorna uma [Promise]
async function async01(async01Start: moment.Moment): Promise<AsyncResult> {
return new Promise(function (resolve) {
console.log("[start of the asynchronous function async01],", time());
// função assíncrona
setTimeout(function () {
console.log("[end of the asynchronous function async01],", time(async01Start));
// a ação assíncrona pode retornar um resultado complexo
// aqui, sucesso
resolve({
prop1: [11, 21, 31],
prop2: "abcd"
});
}, 1000)
});
}
// uma função assíncrona que retorna uma [Promise]
async function async02(async02Start: moment.Moment): Promise<AsyncResult> {
console.log("[start of the asynchronous function async02],", time());
return new Promise(function (resolve) {
// função assíncrona
setTimeout(function () {
console.log("[end of the asynchronous function async02],", time(async02Start));
// a ação assíncrona pode retornar um resultado complexo
// aqui, sucesso
resolve({
prop1: [12, 22, 32],
prop2: "xyzt"
});
}, 2000)
})
}
// uma função assíncrona que retorna uma [Promise]
async function async03(async03Start: moment.Moment): Promise<AsyncResult> {
console.log("[start of the asynchronous function async03],", time());
return new Promise((resolve, reject) => {
// função assíncrona
setTimeout(function () {
console.log("[end of the asynchronous function async03],", time(async03Start));
// a ação assíncrona pode retornar um resultado complexo
// aqui, falha
reject({
prop1: [13, 23, 33],
prop2: "failure"
});
}, 3000)
})
}
// função assíncrona - usando async / await
async function main(): Promise<void> {
const sequentialStart = moment(Date.now());
// execução sequencial das tarefas assíncronas
console.log("------------ sequential execution of the asynchronous tasks started ------------------------")
try {
// execução com espera de [async01]
const async01Start = moment(Date.now());
const result1 = await async01(async01Start);
console.log("[async01 result]=", result1);
// execução com espera de [async02]
const async02Start = moment(Date.now());
console.log("start async02-------------", time());
const result2 = await async02(async02Start);
console.log("[async02 result]=", result2);
// execução com espera de [async03]
const async03Start = moment(Date.now());
console.log("start async03-------------", time());
const result3 = await async03(async03Start);
console.log("[async03 result]=", result3);
} catch (error) {
// uma das ações assíncronas falhou
console.log(sprintf("[sequential error]= %j, %s", error, time(sequentialStart)));
} finally {
// terminado
console.log("[end of the sequential execution of the asynchronous tasks],", time(sequentialStart));
}
const parallelStart = moment(Date.now());
// execução paralela das tarefas assíncronas
console.log("------------ parallel execution of the asynchronous tasks started ------------------------");
try {
const result = await Promise.all([async01(parallelStart), async02(parallelStart), async03(parallelStart)]);
console.log(sprintf("[parallel success], %s, result=%j", time(parallelStart), result));
} catch (error) {
// uma das ações assíncronas falhou
console.log(sprintf("[parallel error], %s, error=%j", time(parallelStart), error));
} finally {
// terminado
console.log(sprintf("[end of the parallel execution of the asynchronous tasks],%s", time(parallelStart)));
}
// terminado
console.log("[end of the main function],", time(sequentialStart));
}
// execução da função principal assíncrona
main();
// será exibido antes das várias msgs das funções assíncronas e de seus evts
console.log("[end of the main code of the script],", time(scriptStart));
// utilitário
function time(start?: moment.Moment): string {
// hora do momento atual
const now = moment(Date.now());
// formatação da hora
let result = "time=" + now.format("HH:mm:ss:SSS");
if (start) {
const duration = now.valueOf() - start.valueOf();
const milliseconds = duration % 1000;
const seconds = Math.floor(duration / 1000);
// formatação da duração
result = result + sprintf(", duration= %s second(s) and %s milliseconds", seconds, milliseconds);
}
// resultado
return result;
}
|
- linha 72: async function main(): Promise<void> — uma função marcada com
async sempre retorna uma Promise, mesmo que seu corpo não o indique explicitamente;
- linha 79:
await async01(async01Start) suspende a execução de main até que a promise seja resolvida, sem bloquear o restante do programa (a palavra-chave await só pode ser usada dentro de uma função async ou no nível superior de um módulo—veja o capítulo “Módulos”, script import-04);
- linhas 76–90: execução sequencial—cada
await espera a tarefa anterior terminar antes de iniciar a seguinte; a duração total é a soma dos três tempos de espera (~6s);
- linhas 102–111: execução paralela, com
await Promise.all([...])—a duração total é a da tarefa mais longa (~3s);
- Um bloco try/catch comum é suficiente para tratar a falha de uma promise aguardada—não há mais necessidade de chamadas .catch() encadeadas como nos scripts anteriores.
npx tsx async/async-06.ts
Resultado da execução:
| [start of the main code of the script], time=07:42:34:907
------------ sequential execution of the asynchronous tasks started ------------------------
[start of the asynchronous function async01], time=07:42:34:914
[end of the main code of the script], time=07:42:34:915, duration= 0 second(s) and 8 milliseconds
[end of the asynchronous function async01], time=07:42:35:916, duration= 1 second(s) and 2 milliseconds
[async01 result]= { prop1: [ 11, 21, 31 ], prop2: 'abcd' }
start async02------------- time=07:42:35:917
[start of the asynchronous function async02], time=07:42:35:918
[end of the asynchronous function async02], time=07:42:37:920, duration= 2 second(s) and 3 milliseconds
[async02 result]= { prop1: [ 12, 22, 32 ], prop2: 'xyzt' }
start async03------------- time=07:42:37:921
[start of the asynchronous function async03], time=07:42:37:921
[end of the asynchronous function async03], time=07:42:40:925, duration= 3 second(s) and 4 milliseconds
[sequential error]= {"prop1":[13,23,33],"prop2":"failure"}, time=07:42:40:925, duration= 6 second(s) and 15 milliseconds
[end of the sequential execution of the asynchronous tasks], time=07:42:40:925, duration= 6 second(s) and 15 milliseconds
------------ parallel execution of the asynchronous tasks started ------------------------
[start of the asynchronous function async01], time=07:42:40:926
[start of the asynchronous function async02], time=07:42:40:926
[start of the asynchronous function async03], time=07:42:40:926
[end of the asynchronous function async01], time=07:42:41:927, duration= 1 second(s) and 2 milliseconds
[end of the asynchronous function async02], time=07:42:42:925, duration= 2 second(s) and 0 milliseconds
[end of the asynchronous function async03], time=07:42:43:926, duration= 3 second(s) and 1 milliseconds
[parallel error], time=07:42:43:927, duration= 3 second(s) and 2 milliseconds, error={"prop1":[13,23,33],"prop2":"failure"}
[end of the parallel execution of the asynchronous tasks],time=07:42:43:927, duration= 3 second(s) and 2 milliseconds
[end of the main function], time=07:42:43:927, duration= 9 second(s) and 17 milliseconds
|
A diferença no tempo total de execução é claramente visível: ~6s no modo sequencial contra ~3s no modo paralelo para as mesmas três tarefas (1s + 2s + 3s).
3.9.8. [async-07] script — extensões de Promise
[NEW since 2019] Este script apresenta quatro extensões introduzidas entre 2020 e 2024, hoje amplamente utilizadas no TypeScript moderno:
| 'use strict';
// ========================================================================
// [NOVO desde 2019] adições à classe Promise
// ========================================================================
// pequena função utilitária: retorna uma promise que é bem-sucedida ou falha após [delay] ms
function task(name: string, delay: number, succeeds: boolean): Promise<string> {
return new Promise<string>((resolve, reject) => {
setTimeout(() => {
if (succeeds) {
resolve(`result of ${name}`);
} else {
reject(`failure of ${name}`);
}
}, delay);
});
}
// ------------------------------------------------------------------------
// 1) Promise.allSettled() (ECMAScript 2020)
// ------------------------------------------------------------------------
// async-05.js mostra Promise.all(): se UMA das promises falhar, o catch é acionado
// e perdemos o resultado das outras promises que, por sua vez, tinham sido bem-sucedidas
// Promise.allSettled() SEMPRE espera até que todas as promises terminem
// (com sucesso ou falha) e retorna o detalhe de cada uma, sem nunca rejeitar
async function demoAllSettled(): Promise<void> {
console.log("--- Promise.allSettled ---");
const results = await Promise.allSettled([
task("task1", 300, true),
task("task2", 200, false),
task("task3", 100, true)
]);
// cada elemento tem a forma { status: "fulfilled", value: ... } ou { status: "rejected", reason: ... }
results.forEach((result, index) => {
if (result.status === "fulfilled") {
console.log(`task${index + 1} succeeded :`, result.value);
} else {
console.log(`task${index + 1} failed :`, result.reason);
}
});
}
// ------------------------------------------------------------------------
// 2) Promise.any() (ECMAScript 2021)
// ------------------------------------------------------------------------
// retorna o resultado da PRIMEIRA promise bem-sucedida (as outras são ignoradas)
// só rejeita se TODAS as promises falharem (com um AggregateError agrupando os erros)
async function demoAny(): Promise<void> {
console.log("--- Promise.any ---");
try {
const result = await Promise.any([
task("slow-mirror", 500, true),
task("fast-mirror", 100, true),
task("broken-mirror", 50, false)
]);
console.log("first available mirror :", result);
} catch (globalError: any) {
// globalError.errors contém a lista de todos os erros individuais
console.log("all the mirrors failed :", globalError.errors);
}
}
// ------------------------------------------------------------------------
// 3) Promise.withResolvers() (ECMAScript 2024)
// ------------------------------------------------------------------------
// antes, para "extrair" as funções resolve/reject do construtor de Promise
// (por exemplo, para chamá-las bem mais tarde, em outro ponto do código), era preciso
// uma variável intermediária um tanto artificial:
// let externalResolve;
// const promise = new Promise(resolve => { externalResolve = resolve; });
// Promise.withResolvers() faz isso diretamente, em uma única expressão
function demoWithResolvers(): Promise<string> {
console.log("--- Promise.withResolvers ---");
const { promise, resolve } = Promise.withResolvers<string>();
// podemos resolver a promise de qualquer lugar, por exemplo em outro callback
setTimeout(() => {
console.log("[external callback] we trigger the resolution of the promise");
resolve("value passed from an external callback");
}, 200);
return promise;
}
// ------------------------------------------------------------------------
// 4) cancelamento de uma operação assíncrona com AbortController
// ------------------------------------------------------------------------
// AbortController permite cancelar uma operação assíncrona em andamento (fetch, temporizadores, ...)
// é o mecanismo padrão usado por [fetch] para timeouts (cf http/fetch-01.js)
function cancellableTask(delay: number, signal: AbortSignal): Promise<string> {
return new Promise<string>((resolve, reject) => {
const timer = setTimeout(() => resolve("finished normally"), delay);
// se o sinal de cancelamento for acionado, interrompemos tudo e rejeitamos
signal.addEventListener("abort", () => {
clearTimeout(timer);
reject(new Error("operation cancelled : " + signal.reason));
});
});
}
async function demoAbortController(): Promise<void> {
console.log("--- AbortController ---");
const controller = new AbortController();
// programamos o cancelamento para daqui a 100 ms, antes do fim normal da tarefa (500 ms)
setTimeout(() => controller.abort("timeout exceeded on the user side"), 100);
try {
const result = await cancellableTask(500, controller.signal);
console.log("result =", result);
} catch (error: any) {
console.log("error :", error.message);
}
}
// execução sucessiva das demonstrações
async function main(): Promise<void> {
await demoAllSettled();
await demoAny();
console.log("--- Promise.withResolvers, result ---", await demoWithResolvers());
await demoAbortController();
}
main();
|
- [Promise.allSettled] (ES2020): ao contrário de Promise.all (script async-05), ele sempre espera todas as promises terminarem — com sucesso ou falha — e retorna os detalhes de cada uma — útil quando você nunca quer perder os resultados das tarefas que tiveram sucesso, mesmo que outra tenha falhado;
- [Promise.any] (ES2021): retorna o resultado da primeira promise que tem sucesso, ignorando as demais — ela só é rejeitada se todas falharem;
- [Promise.withResolvers] (ES2024): extrai
resolve e reject do construtor de Promise em uma única expressão, o que é útil para resolver uma promise mais tarde a partir de outra parte do código;
- [AbortController]: permite cancelar uma operação assíncrona pendente — é o mecanismo padrão usado por
fetch para timeouts (veja o capítulo “As funções HTTP”).
npx tsx async/async-07.ts
Resultado da execução:
| --- Promise.allSettled ---
task1 succeeded : result of task1
task2 failed : failure of task2
task3 succeeded : result of task3
--- Promise.any ---
first available mirror : result of fast-mirror
--- Promise.withResolvers ---
[external callback] we trigger the resolution of the promise
--- Promise.withResolvers, result --- value passed from an external callback
--- AbortController ---
error : operation cancelled : timeout exceeded on the user side
|
3.10. As classes
Apresentamos aqui as classes do ECMAScript, tipadas no TypeScript. Antes disso, lembremos (script class-00, visto anteriormente no capítulo “Funções” sob o nome func-04) que as funções já podem se comportar como classes — é esse mecanismo histórico que a palavra-chave [class] simplifica.
Os scripts deste capítulo estão na pasta [classes] do projeto.

3.10.1. script [class-00]
Lembrete do mecanismo histórico (funções usadas como classes):
| 'use strict';
// uma função pode ser usada como um objeto
// uma casca vazia
// [any]: o tipo de [this] é deliberadamente flexível aqui, porque atribuímos
// propriedades à própria função DEPOIS de sua definição (veja abaixo) -
// um padrão que o TypeScript não consegue inferir sozinho
function f(this: any): void {
}
// à qual atribuímos propriedades externamente
(f as any).prop1 = "val1";
(f as any).show = function (this: any) {
console.log(this.prop1);
};
// uso de f
(f as any).show();
// uma função g que funciona como uma classe
function g(this: any): void {
this.prop2 = "val2";
this.show = function (this: any) {
console.log(this.prop2);
};
}
// instanciação da função com [new]
new (g as any)().show();
|
npx tsx classes/class-00.ts
Resultado da execução:
Nota: O ES6 introduziu a palavra-chave `class`, que permite obter o mesmo resultado de forma muito mais legível e confiável, sem recorrer a esse artifício funcional — como mostram os scripts a seguir.
3.10.2. script [class-01]
Este script define uma classe chamada [Person], com um construtor, getters/setters e o método toString:
| // classe
class Person {
private _lastName!: string;
private _firstName!: string;
private _age!: number;
// construtor
constructor(lastName: string, firstName: string, age: number) {
this.lastName = lastName;
this.firstName = firstName;
this.age = age;
}
// getters e setters
get lastName(): string {
return this._lastName;
}
set lastName(value: string) {
this._lastName = value;
}
get firstName(): string {
return this._firstName;
}
set firstName(value: string) {
this._firstName = value;
}
get age(): number {
return this._age;
}
set age(value: number) {
this._age = value;
}
// toString em JSON
toString(): string {
return JSON.stringify(this);
}
}
// uso da classe
function main(): void {
const person = new Person("Poirot", "Hercule", 66);
console.log("person=", person.toString(), typeof (person), person instanceof (Person));
}
// chamada a main
main();
|
- linha 2: [class] introduz a classe;
- linha 9: [constructor] é o seu construtor — só pode haver um por classe;
- linhas 4–6: Os campos _lastName, _firstName e _age são declarados com o modificador [private] — o que os torna acessíveis apenas de dentro da classe, ao contrário de uma simples convenção de nomenclatura. O ! (*definite assignment assertion*) informa ao TypeScript que esses campos serão de fato atribuídos antes de qualquer leitura, mesmo que isso não seja diretamente visível em sua declaração (o construtor, por meio dos setters, cuida disso);
- linhas 16–35: getters e setters — sintaxe idêntica à vista nos objetos literais (capítulo “Objetos literais”, script obj-03), mas integrada à classe;
- linha 46:
person instanceof (Person) — é possível determinar o tipo exato de uma instância de classe, ao contrário do que ocorre com objetos literais.
npx tsx classes/class-01.ts
Resultado da execução:
| person= {"_lastName":"Poirot","_firstName":"Hercule","_age":66} object true
|
3.10.3. script [class-02] — herança
Este script demonstra a herança com a palavra-chave [extends]. A classe Person é isolada primeiro em seu próprio arquivo, Person.ts:
| // classe
class Person {
// propriedades privadas (acessadas pelos getters/setters abaixo)
// [!]: afirmamos ao TypeScript que elas serão atribuídas antes de serem lidas
// (aqui, pelo construtor, que chama os setters)
private _lastName!: string;
private _firstName!: string;
private _age!: number;
// construtor
constructor(lastName: string, firstName: string, age: number) {
this.lastName = lastName;
this.firstName = firstName;
this.age = age;
}
// getters e setters
get lastName(): string {
return this._lastName;
}
set lastName(value: string) {
this._lastName = value;
}
get firstName(): string {
return this._firstName;
}
set firstName(value: string) {
this._firstName = value;
}
get age(): number {
return this._age;
}
set age(value: number) {
this._age = value;
}
// toString em JSON
toString(): string {
return JSON.stringify(this);
}
}
// export da classe
export default Person;
|
O script [class-02] cria uma classe [Teacher] derivada de Person:
| // importações
// [atualização 2026] com o ESM nativo do node, a extensão .js é obrigatória
// em caminhos relativos (era opcional com o loader [esm] usado em 2019)
import Person from './Person.js';
// classe
class Teacher extends Person {
private _subject!: string;
// construtor
constructor(lastName: string, firstName: string, age: number, subject: string) {
super(lastName, firstName, age);
this.subject = subject;
}
// getters e setters
get subject(): string {
return this._subject;
}
set subject(value: string) {
this._subject = value;
}
}
// uso da classe
function main(): void {
const teacher = new Teacher("Poirot", "Hercule", 66, "detective");
console.log("teacher=", teacher.toString(), typeof (teacher), teacher instanceof Teacher);
}
// chamada a main
main();
|
- linha 5: import Person from './Person.js' — a classe é importada de seu módulo. A extensão .js (e não .ts) é obrigatória na resolução de módulos moderna do Node.js, mesmo que o arquivo-fonte seja um arquivo .ts (veja o capítulo “Instalação”);
- linha 8: class Teacher extends Person — Teacher herda todos os membros de Person e acrescenta uma propriedade _subject com seu getter/setter;
- linha 14: super(lastName, firstName, age) chama o construtor da classe pai, que inicializa _lastName, _firstName e _age;
- linha 31:
teacher instanceof Teacher — TypeScript/JavaScript conhece o tipo exato da instância, mesmo após a herança.
npx tsx classes/class-02.ts
Resultado da execução:
| teacher= {"_lastName":"Poirot","_firstName":"Hercule","_age":66,"_subject":"detective"} object true
|
3.10.4. script [class-03] — sobrescrita de método
Este script demonstra que uma classe filha pode sobrescrever um método de sua classe pai — neste caso, toString:
| // importações
// [atualização 2026] com o ESM nativo do node, a extensão .js é obrigatória
// em caminhos relativos (era opcional com o loader [esm] usado em 2019)
import Person from './Person.js';
// classe
class Teacher extends Person {
private _subject!: string;
// construtor
constructor(lastName: string, firstName: string, age: number, subject: string) {
super(lastName, firstName, age);
this.subject = subject;
}
// getters e setters
get subject(): string {
return this._subject;
}
set subject(value: string) {
this._subject = value;
}
// redefinição de toString
toString(): string {
return "[Teacher]" + JSON.stringify(this);
}
}
// uso da classe
function main(): void {
const teacher = new Teacher("Poirot", "Hercule", 66, "detective");
console.log("teacher=", teacher.toString(), typeof (teacher), teacher instanceof Teacher);
}
// chamada a main
main();
|
npx tsx classes/class-03.ts
Resultado da execução:
| teacher= [Teacher]{"_lastName":"Poirot","_firstName":"Hercule","_age":66,"_subject":"detective"} object true
|
3.10.5. script [class-04] — polimorfismo
Este script demonstra o polimorfismo em ação: onde uma função espera um parâmetro do tipo Person, podemos passar um tipo derivado como Teacher, já que ele possui todos os atributos de Person. Primeiro, isolamos Teacher em seu próprio módulo, Teacher.ts:
| // importações
// [atualização 2026] com o ESM nativo do node, a extensão .js é obrigatória
// em caminhos relativos (era opcional com o loader [esm] usado em 2019)
import Person from './Person.js';
// classe
class Teacher extends Person {
// propriedade privada (acessada pelo getter/setter abaixo)
private _subject!: string;
// construtor
constructor(lastName: string, firstName: string, age: number, subject: string) {
super(lastName, firstName, age);
this.subject = subject;
}
// getters e setters
get subject(): string {
return this._subject;
}
set subject(value: string) {
this._subject = value;
}
}
// export da classe
export default Teacher;
|
O script [class-04] usa esse tipo de forma polimórfica:
| // importações
// [atualização 2026] com o ESM nativo do node, a extensão .js é obrigatória
// em caminhos relativos (era opcional com o loader [esm] usado em 2019)
import Teacher from './Teacher.js';
import Person from './Person.js';
// função que aceita uma pessoa como parâmetro
function show(person: Person): void {
// em todos os casos
console.log("parameter=", person.toString(), typeof (person));
// instância de Person
if (person instanceof Person) {
console.log("person=", person.toString());
}
// instância de Teacher
if (person instanceof Teacher) {
console.log("teacher=", person.toString());
}
}
// chamada de show com um professor
show(new Teacher("Poirot", "Hercule", 66, "detective"));
show(new Person("Marple", "Miss", 70));
|
- linha 8: function show(person: Person): void — a função espera um parâmetro do tipo Person, mas aceita qualquer tipo derivado (Teacher) — esse é o princípio da substituição, fundamental na programação orientada a objetos;
- linhas 11 –18:
instanceof permite adaptar o comportamento ao tipo real do objeto recebido, além de seu tipo declarado.
npx tsx classes/class-04.ts
Resultado da execução:
| parameter= {"_lastName":"Poirot","_firstName":"Hercule","_age":66,"_subject":"detective"} object
person= {"_lastName":"Poirot","_firstName":"Hercule","_age":66,"_subject":"detective"}
teacher= {"_lastName":"Poirot","_firstName":"Hercule","_age":66,"_subject":"detective"}
parameter= {"_lastName":"Marple","_firstName":"Miss","_age":70} object
person= {"_lastName":"Marple","_firstName":"Miss","_age":70}
|
3.10.6. script [class-05] — campos privados nativos
[NEW since 2019] Os scripts anteriores usam o modificador private (TypeScript, _lastName, _firstName...), um mecanismo de proteção que existe apenas em tempo de compilação — em tempo de execução, em JavaScript puro, esses campos continuam sendo propriedades comuns. Desde o ECMAScript 2022, existem verdadeiros campos privados, prefixados com #, invisíveis e inacessíveis mesmo em tempo de execução:
| 'use strict';
// ========================================================================
// [NOVO desde 2019] campos privados e blocos estáticos (ECMAScript 2022)
// ========================================================================
// em class-01.js, o encapsulamento era simulado por convenção: uma propriedade
// chamada [_name] (com sublinhado) acessada por um getter/setter [name].
// MAS nada impedia realmente de escrever person._name = "xyz" de fora!
// desde o ECMAScript 2022, podemos declarar campos privados DE VERDADE com um [#]
// antes do nome: eles só são acessíveis de dentro da classe.
class BankAccount {
// campo privado: existe e é visível SOMENTE nos métodos desta classe
#balance: number;
// campo privado com valor padrão
#history: string[] = [];
// campo público normal (sem #): acessível de fora, como antes
holder: string;
constructor(holder: string, initialBalance: number = 0) {
this.holder = holder;
this.#balance = initialBalance;
}
// método público que dá acesso controlado ao campo privado
get balance(): number {
return this.#balance;
}
deposit(amount: number): void {
this.#balance += amount;
// #addToHistory é um método privado, que só pode ser chamado daqui
this.#addToHistory(`deposit of ${amount}`);
}
withdraw(amount: number): void {
if (amount > this.#balance) {
throw new Error("insufficient balance");
}
this.#balance -= amount;
this.#addToHistory(`withdrawal of ${amount}`);
}
// método privado: o [#] também funciona em métodos
#addToHistory(operation: string): void {
this.#history.push(operation);
}
displayHistory(): void {
console.log(`history of ${this.holder} :`, this.#history);
}
}
// uso normal
const account = new BankAccount("Dupont", 100);
account.deposit(50);
account.withdraw(30);
console.log("balance =", account.balance); // pelo getter público
account.displayHistory();
// não podemos acessar o campo privado diretamente de fora
console.log("direct account.#balance : impossible, causes a syntax error if we try");
// console.log(account.#balance); // descomentar esta linha provoca um erro de compilação do TypeScript
// também não podemos lê-lo com a notação [ ] como em uma propriedade normal
console.log("account['#balance'] =", (account as any)["#balance"]); // -> undefined, não é a mesma coisa
// ------------------------------------------------------------------------
// também existem campos e métodos STATIC privados
// ------------------------------------------------------------------------
class IdGenerator {
// campo static privado: compartilhado por todas as instâncias, invisível de fora
static #lastId: number = 0;
// bloco de inicialização static: executado uma única vez, quando a classe é carregada
// útil para uma inicialização complexa que um simples "= valor" não permite
static {
console.log("[static block] initialization of IdGenerator");
IdGenerator.#lastId = 1000; // valor inicial personalizado
}
// método static público que dá acesso controlado ao campo static privado
static nextId(): number {
IdGenerator.#lastId++;
return IdGenerator.#lastId;
}
}
console.log("nextId() =", IdGenerator.nextId());
console.log("nextId() =", IdGenerator.nextId());
console.log("nextId() =", IdGenerator.nextId());
|
- [#balance] (linha 15), [#history] (linha 18): campos privados de verdade — ao contrário de _lastName no script class-01, é impossível acessá-los de fora da classe, mesmo via account['#balance'] (linha 69), que retorna undefined em vez do valor real;
- [#addToHistory] (linha 48): um método privado, que só pode ser chamado de dentro da classe;
- [static { ... }] (linhas 80–83): um bloco de inicialização estático (ES2022), executado uma única vez quando a classe é carregada — útil para inicializações mais complexas que uma simples atribuição;
- [static #lastId] (linha 76): um campo estático privado, compartilhado por todas as instâncias, mas invisível do exterior.
npx tsx classes/class-05.ts
Resultado da execução:
| balance = 120
history of Dupont : [ 'deposit of 50', 'withdrawal of 30' ]
direct account.#balance : impossible, causes a syntax error if we try
account['#balance'] = undefined
[static block] initialization of IdGenerator
nextId() = 1001
nextId() = 1002
nextId() = 1003
|
3.11. Novos recursos do ECMAScript 2020–2024
Os capítulos anteriores já abordaram, ao longo do caminho, a maior parte dos novos recursos da linguagem introduzidos desde 2019 — encadeamento opcional e coalescência nula (basics-09), Object.hasOwn e structuredClone (obj-09), novos métodos de array (arr-05), replaceAll/matchAll (str-07), campos privados nativos (class-05), Error com cause (excep-04), await de nível superior (import-04) e as extensões de Promise (async-07).
Este capítulo reúne as duas últimas novidades do ECMAScript 2024 que não couberam em nenhum capítulo existente: [Object.groupBy]/[Map.groupBy] e [Array.fromAsync]. O script está na pasta [whats-new] do projeto.

3.11.1. script [groupBy-and-fromAsync]
| 'use strict';
// ========================================================================
// [NOVO desde 2019] Object.groupBy, Map.groupBy, Array.fromAsync (ECMAScript 2024)
// ========================================================================
// ------------------------------------------------------------------------
// 1) Object.groupBy(array, groupingFunction)
// ------------------------------------------------------------------------
// antes, para agrupar os elementos de um array segundo um critério, era preciso
// escrever você mesmo um laço com reduce() (cf. arrays/arr-04.js para reduce)
interface Student {
name: string;
grade: number;
}
const students: Student[] = [
{ name: "Ana", grade: 15 },
{ name: "Léo", grade: 8 },
{ name: "Nora", grade: 12 },
{ name: "Théo", grade: 6 },
{ name: "Zoé", grade: 17 }
];
// forma antiga, com reduce()
const groupsWithReduce = students.reduce((accumulator: Record<string, Student[]>, student) => {
const category = student.grade >= 10 ? "passed" : "failed";
// se ainda não houver um array para esta categoria, nós o criamos
(accumulator[category] ??= []).push(student);
return accumulator;
}, {});
console.log("with reduce :", groupsWithReduce);
// forma nova, muito mais legível, com Object.groupBy
const groups = Object.groupBy(students, student => (student.grade >= 10 ? "passed" : "failed"));
console.log("with Object.groupBy :", groups);
console.log("passed =", groups.passed);
console.log("failed =", groups.failed);
// Map.groupBy funciona da mesma maneira, mas retorna um [Map] em vez de um objeto literal
// útil quando as chaves de agrupamento não são strings (ex.: objetos, números)
const groupsInMap = Map.groupBy(students, student => student.grade >= 10);
console.log("with Map.groupBy, key [true] (passed) =", groupsInMap.get(true));
console.log("with Map.groupBy, key [false] (failed) =", groupsInMap.get(false));
// ------------------------------------------------------------------------
// 2) Array.fromAsync(asyncIterable)
// ------------------------------------------------------------------------
// Array.from() (ES2015) pode construir um array a partir de um iterável síncrono
// Array.fromAsync() pode fazer o mesmo a partir de um iterável ASSÍNCRONO,
// ou seja, uma fonte que produz seus elementos um a um, ao longo do tempo
// (por exemplo: leitura de um fluxo de rede página por página)
// um gerador assíncrono que produz 3 valores, com um pequeno atraso entre cada um
async function* pageGenerator(): AsyncGenerator<string> {
for (let i = 1; i <= 3; i++) {
// simulamos uma espera de rede antes de cada página
await new Promise(resolve => setTimeout(resolve, 100));
yield `page ${i}`;
}
}
async function demoFromAsync(): Promise<void> {
console.log("--- Array.fromAsync ---");
// sem Array.fromAsync, seria necessário um laço manual "for await...of"
const pages = await Array.fromAsync(pageGenerator());
console.log("pages =", pages);
}
demoFromAsync();
|
- Linha 33: [Object.groupBy(array, groupingFunction)] agrupa os elementos de um array com base no resultado de uma função de classificação — muito mais legível que a construção manual com
reduce() (compare as duas construções: linhas 24–29 e linha 33);
- o resultado de Object.groupBy é um objeto sem protótipo ([Object: null prototype]) — um detalhe visível em tempo de execução, que evita certas armadilhas ligadas às propriedades herdadas de Object.prototype (como toString, hasOwnProperty...) caso alguma categoria tenha esse nome;
- linha 40: [Map.groupBy] funciona de forma idêntica, mas retorna um Map em vez de um objeto literal — essencial sempre que as chaves de agrupamento não são strings (neste caso, booleanos);
- [Array.fromAsync(asyncIterable)] constrói um array a partir de uma fonte assíncrona — um gerador
async function\* , por exemplo — sem precisar escrever manualmente um for laço para acumular os resultados.
npx tsx whats-new/groupBy-and-fromAsync.ts
Resultado da execução:
| with reduce : {
passed: [
{ name: 'Ana', grade: 15 },
{ name: 'Nora', grade: 12 },
{ name: 'Zoé', grade: 17 }
],
failed: [ { name: 'Léo', grade: 8 }, { name: 'Théo', grade: 6 } ]
}
with Object.groupBy : [Object: null prototype] {
passed: [
{ name: 'Ana', grade: 15 },
{ name: 'Nora', grade: 12 },
{ name: 'Zoé', grade: 17 }
],
failed: [ { name: 'Léo', grade: 8 }, { name: 'Théo', grade: 6 } ]
}
passed = [
{ name: 'Ana', grade: 15 },
{ name: 'Nora', grade: 12 },
{ name: 'Zoé', grade: 17 }
]
failed = [ { name: 'Léo', grade: 8 }, { name: 'Théo', grade: 6 } ]
with Map.groupBy, key [true] (passed) = [
{ name: 'Ana', grade: 15 },
{ name: 'Nora', grade: 12 },
{ name: 'Zoé', grade: 17 }
]
with Map.groupBy, key [false] (failed) = [ { name: 'Léo', grade: 8 }, { name: 'Théo', grade: 6 } ]
--- Array.fromAsync ---
pages = [ 'page 1', 'page 2', 'page 3' ]
|
3.11.2. Tabela-resumo
Resumimos, por versão do ECMAScript, todos os novos recursos apresentados neste curso desde o capítulo “Básico”:
- [ES2020]: encadeamento opcional ?., coalescência nula ??, BigInt, Promise.allSettled, String.matchAll;
- [ES2021]: atribuição lógica ||=/&&=/??=, separadores numéricos 1_000_000, Promise.any, String.replaceAll;
- [ES2022]: campos e métodos privados #name, blocos de inicialização estáticos, Object.hasOwn, Array.at, await de nível superior, Error com cause;
- [ES2023]: findLast/findLastIndex, métodos imutáveis toSorted/toReversed/toSpliced/with;
- [ES2024]: Object.groupBy/Map.groupBy, Array.fromAsync, Promise.withResolvers, String.isWellFormed/toWellFormed.
Os capítulos seguintes descrevem as novidades do ECMAScript 2026, bem como [Temporal], o substituto moderno do objeto Date.
3.12. Novos recursos do ECMAScript 2026
O ECMAScript 2026 (a 17ª edição da linguagem) foi oficialmente finalizado pelo TC39 em 2026. Segundo o texto oficial da especificação (https://tc39.es/ecma262/2026/), essa edição acrescentou: Math.sumPrecise para somar um conjunto de números minimizando a perda de precisão; Iterator.concat para encadear iteradores; Array.fromAsync (já apresentado no capítulo anterior); Error.isError para identificar objetos de erro de forma confiável; métodos em Map.prototype e WeakMap.prototype para fornecer um valor padrão durante uma leitura; métodos em Uint8Array para conversões hexadecimais e Base64; um parâmetro context para os revivers de JSON.parse; e JSON.rawJSON para ajustar com precisão a saída de JSON.stringify.
3.12.1. ⚠️ Um aviso importante antes de começar
O estágio 4 do TC39 garante que o comportamento de um recurso não mudará mais, mas não garante sua disponibilidade imediata em todos os engines JavaScript. Ao preparar este capítulo, um exemplo concreto mostrou isso claramente: [Math.sumPrecise] causa o erro “TypeError: Math.sumPrecise is not a function”, mesmo em versões recentes do Node.js. Isso não é um bug deste curso: o V8 (o engine usado pelo Node e pelo Chrome) simplesmente ainda não implementou esse recurso — ao contrário do Firefox, do Safari e do Bun, que já o têm (fonte: issue oficial do repositório do TypeScript, github.com/microsoft/TypeScript/issues/63427).
É por isso que cada script deste capítulo usa typeof para verificar por conta própria se o recurso que demonstra está disponível antes de usá-lo, e exibe uma mensagem clara caso não esteja — em vez de falhar abruptamente. Essa é, por si só, uma boa prática ao usar recursos muito recentes da linguagem.
Importante: Todos os scripts deste capítulo foram realmente executados no ambiente de desenvolvimento deste curso (Node.js 26.7.0); alguns deles exibem a mensagem “not available”, que é um resultado real e não uma suposição. Na sua máquina, com outra versão do Node.js, alguns desses scripts podem exibir um resultado real em vez dessa mensagem — fique à vontade para comparar.
Os scripts a seguir estão na pasta [ecmascript-2026]:

3.12.2. script [01-math-sumPrecise]
| 'use strict';
// ========================================================================
// [NOVO ECMAScript 2026] Math.sumPrecise()
// ========================================================================
// [atualização] no momento em que este script é escrito, o V8 (portanto node e Chrome)
// AINDA NÃO implementa Math.sumPrecise, enquanto Firefox, Safari e Bun
// já o têm. Este é um exemplo concreto da distância que pode existir entre
// "o recurso entrou na especificação oficial da linguagem"
// e "todos os engines JavaScript o implementaram de fato": o TC39 Stage 4
// (atingido em 28/07/2025 para este recurso) garante que o
// comportamento não mudará mais, mas NÃO garante uma disponibilidade
// imediata em todos os lugares. Veja ecmascript-2026/README.md para os detalhes e as
// fontes.
// Para verificar por conta própria se o SEU node já tem este recurso:
// node -e "console.log(typeof Math.sumPrecise)"
// somar números de ponto flutuante com + acumula erros de arredondamento,
// porque cada número é representado em binário de forma imprecisa
const numbers: number[] = [0.1, 0.2, 0.3, 0.1, 0.2, 0.3, 0.1, 0.2, 0.3, 0.1];
// ------------------------------------------------------------------------
// 1) a forma antiga, com reduce(): o resultado não é exato
// ------------------------------------------------------------------------
const sumWithReduce = numbers.reduce((accumulator, value) => accumulator + value, 0);
console.log("sum with reduce =", sumWithReduce);
// esperamos exatamente 1.9, mas o resultado costuma conter casas decimais espúrias
// (ex.: 1.9000000000000001) por causa de erros de arredondamento que se acumulam ao longo das somas
// ------------------------------------------------------------------------
// 2) Math.sumPrecise(): soma todos os números com exatidão
// ------------------------------------------------------------------------
// diferentemente de um laço de somas sucessivas, o algoritmo usado internamente
// evita acumular os erros de arredondamento intermediários
if (typeof Math.sumPrecise === "function") {
const preciseSum = Math.sumPrecise(numbers);
console.log("sum with Math.sumPrecise =", preciseSum);
} else {
// aqui evitamos uma falha brusca (TypeError) para continuar didático:
// esta mensagem será exibida enquanto o seu engine JavaScript ainda não tiver
// implementado este recurso, embora ele já esteja finalizado na especificação
console.log("Math.sumPrecise is not yet available on this JavaScript engine",
"(see the comment at the top of this file)");
}
// ------------------------------------------------------------------------
// por que é útil: cálculos financeiros, contábeis, científicos -
// em qualquer lugar em que um pequeno erro de arredondamento repetido possa se tornar um bug real
// (ex.: o total de uma fatura que nunca fecha no centavo)
// ------------------------------------------------------------------------
|
npx tsx ecmascript-2026/01-math-sumPrecise.ts
Resultado da execução:
| sum with reduce = 1.9000000000000004
Math.sumPrecise is not yet available on this JavaScript engine (see the comment at the top of this file)
|
3.12.3. script [02-iterator-concat]
[Iterator.concat] concatena vários iteráveis (array, Set, gerador etc.) em um único iterador lazy: os elementos são gerados apenas conforme a necessidade, sem construir uma coleção intermediária completa — ao contrário do operador spread [...a, ...b], que copia tudo imediatamente para a memória.
| 'use strict';
// ========================================================================
// [NOVO ECMAScript 2026] Iterator.concat()
// ========================================================================
// [Node 26+ - listado oficialmente nas notas de versão do node 26.0.0:
// veja https://nodejs.org/en/blog/release/v26.0.0 - portanto normalmente já
// disponível se você estiver no node 26. Se não for o caso, verifique com:
// node -e "console.log(typeof Iterator.concat)"
// veja também ecmascript-2026/README.md para o caso dos outros novos recursos
// desta pasta, que nem todos têm o mesmo nível de disponibilidade]
// às vezes temos várias fontes de dados para percorrer uma após a outra
// (por exemplo: vários arrays, ou um array e depois um Set, ...)
const firstWave: string[] = ["Ana", "Léo"];
const secondWave: Set<string> = new Set(["Nora", "Théo"]);
const thirdWave: string[] = ["Zoé"];
// ------------------------------------------------------------------------
// 1) a forma antiga: era preciso reunir tudo em um novo array
// ------------------------------------------------------------------------
const allGuestsArray: string[] = [...firstWave, ...secondWave, ...thirdWave];
console.log("with spread :", allGuestsArray);
// inconveniente: isso cria um novo array NA MEMÓRIA com todos os elementos copiados,
// mesmo que só precisemos dos 2 primeiros (ex.: para uma exibição paginada)
// ------------------------------------------------------------------------
// 2) Iterator.concat(): encadeia os iteráveis sem copiá-los antes
// ------------------------------------------------------------------------
// Iterator.concat aceita qualquer tipo de iterável (array, Set, Map, gerador...)
// e retorna um iterador "lazy": os elementos só são produzidos à medida que são necessários
if (typeof Iterator.concat === "function") {
const allGuests = Iterator.concat(firstWave, secondWave, thirdWave);
console.log("-----------------------");
for (const guest of allGuests) {
console.log("guest =", guest);
}
// ------------------------------------------------------------------------
// vantagem da avaliação lazy: podemos parar no meio do caminho
// sem ter pago o custo de construir antecipadamente uma coleção completa
// ------------------------------------------------------------------------
const firstThree = Iterator.concat(firstWave, secondWave, thirdWave)
.take(3)
.toArray();
console.log("first three guests =", firstThree);
} else {
console.log("Iterator.concat is not available on this JavaScript engine",
"(see the comment at the top of this file)");
}
|
npx tsx ecmascript-2026/02-iterator-concat.ts
Resultado da execução:
| with spread : [ 'Ana', 'Léo', 'Nora', 'Théo', 'Zoé' ]
-----------------------
guest = Ana
guest = Léo
guest = Nora
guest = Théo
guest = Zoé
first three guests = [ 'Ana', 'Léo', 'Nora' ]
|
3.12.4. script [03-error-isError]
[Error.isError] detecta de forma confiável se um valor é um erro, mesmo quando ele vem de outro "realm" JavaScript (um contexto de execução isolado — um iframe, um worker ou o módulo vm do Node.js): cada realm tem sua própria classe Error , o que faz instanceof Error falhar, como o script demonstra na prática:
| 'use strict';
// ========================================================================
// [NOVO ECMAScript 2026] Error.isError()
// ========================================================================
// [situação de disponibilidade a verificar por conta própria: veja ecmascript-2026/README.md.
// Alguns novos recursos do ES2026 (como Math.sumPrecise) ainda faltam
// no V8 apesar de terem atingido o Stage 4 - não é impossível que seja também o caso
// aqui. Verifique com: node -e "console.log(typeof Error.isError)"]
// até agora, para saber se um valor é um erro, usávamos [instanceof Error]
// (cf. exceptions/excep-03.ts) - isso funciona bem... exceto em alguns casos complicados
// ------------------------------------------------------------------------
// 1) a armadilha do [instanceof] com vários "realms" JavaScript
// ------------------------------------------------------------------------
// um "realm" é um contexto de execução JavaScript isolado: por exemplo,
// um iframe em um navegador, um worker ou o módulo [vm] do node, que permite
// executar código em um contexto separado. Cada realm tem a SUA PRÓPRIA classe [Error],
// distinta da do realm principal.
import vm from 'node:vm';
// executamos "new Error('from elsewhere')" em um realm separado
const errorFromAnotherRealm: unknown = vm.runInNewContext("new Error('from elsewhere')");
console.log("errorFromAnotherRealm =", errorFromAnotherRealm);
// [instanceof Error] falha aqui: não é a MESMA classe [Error] que a nossa,
// embora o objeto SEJA, conceitualmente, um erro
console.log("errorFromAnotherRealm instanceof Error :", errorFromAnotherRealm instanceof Error);
// ------------------------------------------------------------------------
// 2) Error.isError(): detecção confiável, mesmo entre realms diferentes
// ------------------------------------------------------------------------
if (typeof Error.isError === "function") {
console.log("Error.isError(errorFromAnotherRealm) :", Error.isError(errorFromAnotherRealm));
// para comparação, em um erro "normal" (mesmo realm), as duas formas de fazer
// dão o mesmo resultado
const normalError = new Error("classic error");
console.log("normalError instanceof Error :", normalError instanceof Error);
console.log("Error.isError(normalError) :", Error.isError(normalError));
// e em um valor que claramente não é um erro
console.log("Error.isError('abc') :", Error.isError("abc"));
console.log("Error.isError(null) :", Error.isError(null));
} else {
console.log("Error.isError is not available on this JavaScript engine",
"(see the comment at the top of this file) - but the [instanceof] trap",
"demonstrated above is quite real and already observable");
}
|
npx tsx ecmascript-2026/03-error-isError.ts
Resultado da execução:
| errorFromAnotherRealm = Error: from elsewhere
at evalmachine.<anonymous>:1:1
at Script.runInContext (node:vm:150:12)
at Script.runInNewContext (node:vm:155:17)
at Object.runInNewContext (node:vm:311:38)
at <anonymous> (c:\Data\st-2026\GitHub Pages\fr_FR2\downloads\typescript-sept-2026\ecmascript-2026\03-error-isError.ts:23:43)
at ModuleJob.run (node:internal/modules/esm/module_job:569:25)
at async node:internal/modules/esm/loader:650:26
at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:101:5)
errorFromAnotherRealm instanceof Error : false
Error.isError(errorFromAnotherRealm) : true
normalError instanceof Error : true
Error.isError(normalError) : true
Error.isError('abc') : false
|
Este script ilustra um ponto interessante mesmo sem Error.isError disponível: a linha errorFromAnotherRealm instanceof Error : false mostra claramente a armadilha real que Error.isError deveria resolver — e, no entanto, o objeto é, conceitualmente, um verdadeiro erro.
3.12.5. script [04-map-weakmap-getOrInsert]
[Map.prototype.getOrInsert]/[getOrInsertComputed] atendem a uma necessidade muito comum: “se a chave já existe, use o seu valor; caso contrário, crie um valor padrão e armazene-o”, tudo em uma única linha, em vez de um verboso if (!map.has(key)) { map.set(...) }. O mesmo princípio vale para WeakMap.
| 'use strict';
// ========================================================================
// [NOVO ECMAScript 2026] Map.prototype.getOrInsert / getOrInsertComputed
// ========================================================================
// [Node 26+ - listado oficialmente nas notas de versão do node 26.0.0:
// veja https://nodejs.org/en/blog/release/v26.0.0 - portanto normalmente já
// disponível se você estiver no node 26. Se não for o caso, verifique com:
// node -e "console.log(typeof Map.prototype.getOrInsert)"
// veja também ecmascript-2026/README.md para o caso dos outros novos recursos
// desta pasta, que nem todos têm o mesmo nível de disponibilidade]
// uma necessidade muito frequente: "se a chave já existe no Map, pegar seu valor;
// caso contrário, criar um valor padrão, armazená-lo e depois usá-lo"
// ------------------------------------------------------------------------
// 1) a forma antiga: if/has() e depois set() - verbosa e fácil de errar
// ------------------------------------------------------------------------
const registrationsByWorkshop = new Map<string, string[]>();
function registerOldWay(workshop: string, participant: string): void {
if (!registrationsByWorkshop.has(workshop)) {
registrationsByWorkshop.set(workshop, []);
}
registrationsByWorkshop.get(workshop)!.push(participant);
// o "!" é necessário aqui: o TypeScript não tem como saber, neste ponto exato,
// que o .get() que vem após um .set() logo antes terá necessariamente sucesso
}
registerOldWay("cooking", "Ana");
registerOldWay("cooking", "Léo");
console.log("with the old way :", registrationsByWorkshop);
if (typeof Map.prototype.getOrInsert !== "function") {
console.log("Map.prototype.getOrInsert is not available on this JavaScript engine",
"(see the comment at the top of this file) - only part 1) above could be executed");
} else {
// ------------------------------------------------------------------------
// 2) Map.prototype.getOrInsert(): a mesma coisa, em uma única linha
// ------------------------------------------------------------------------
const registrations2 = new Map<string, string[]>();
const register = (workshop: string, participant: string): void => {
// retorna o array existente para [workshop], ou o inicializa com [] se ainda não existir
registrations2.getOrInsert(workshop, []).push(participant);
}
register("pottery", "Nora");
register("pottery", "Théo");
console.log("with getOrInsert :", registrations2);
// ------------------------------------------------------------------------
// 3) getOrInsertComputed(): o valor padrão é calculado SOMENTE se necessário
// ------------------------------------------------------------------------
// com getOrInsert(key, value), o [value] padrão é SEMPRE avaliado,
// mesmo quando a chave já existe e não precisamos dele (aqui não
// importa para um array vazio [], mas pode importar para um cálculo custoso)
const counters = new Map<string, number>();
const increment = (key: string): void => {
// o callback é chamado SOMENTE se a chave ainda não existir no Map
const value = counters.getOrInsertComputed(key, () => {
console.log(`[computing the initial value for "${key}"]`);
return 0;
});
counters.set(key, value + 1);
}
increment("visits");
increment("visits"); // aqui, o callback NÃO será executado de novo
increment("clicks");
console.log("counters =", counters);
// ------------------------------------------------------------------------
// 4) WeakMap.prototype.getOrInsert / getOrInsertComputed: mesmo princípio,
// para associar dados adicionais a objetos sem impedir sua
// coleta pelo garbage collector
// ------------------------------------------------------------------------
interface Metadata {
views: number;
}
const metadataByObject = new WeakMap<object, Metadata>();
const recordAView = (object: object): void => {
const metadata = metadataByObject.getOrInsertComputed(object, () => ({ views: 0 }));
metadata.views++;
}
const article = { title: "Discovering the WeakMap" };
recordAView(article);
recordAView(article);
console.log("metadata of the article =", metadataByObject.get(article));
}
|
npx tsx ecmascript-2026/04-map-weakmap-getOrInsert.ts
Resultado da execução:
| with the old way : Map(1) { 'cooking' => [ 'Ana', 'Léo' ] }
with getOrInsert : Map(1) { 'pottery' => [ 'Nora', 'Théo' ] }
[computing the initial value for "visits"]
[computing the initial value for "clicks"]
counters = Map(2) { 'visits' => 2, 'clicks' => 1 }
metadata of the article = { views: 2 }
|
3.12.6. script [05-uint8array-base64-hex]
Uint8Array (um array de bytes brutos) agora inclui novos métodos para converter de e para base64 e hexadecimal — formatos comumente usados para transmitir dados binários em JSON ou em URLs — sem depender de um pacote de terceiros:
| 'use strict';
// ========================================================================
// [NOVO ECMAScript 2026] Uint8Array: conversão para base64 e hexadecimal
// ========================================================================
// [situação de disponibilidade a verificar por conta própria: veja ecmascript-2026/README.md.
// Alguns novos recursos do ES2026 (como Math.sumPrecise) ainda faltam
// no V8 apesar de terem atingido o Stage 4 - não é impossível que seja também o caso
// aqui. Verifique com: node -e "console.log(typeof Uint8Array.prototype.toBase64)"]
// [Uint8Array] é um array tipado que armazena bytes brutos (valores 0-255) -
// por exemplo o conteúdo de um arquivo, uma imagem ou dados recebidos pela rede
// antes de 2026, para codificar esses bytes em base64 (o formato usado, por exemplo,
// em URLs "data:", ou para transmitir dados binários em JSON),
// era preciso passar por funções indiretas ou pacotes de terceiros (buffer no lado do node,
// btoa/atob no lado do navegador - imperfeitos e não projetados originalmente para isso)
const bytes = new Uint8Array([72, 101, 108, 108, 111]); // "Hello" em códigos ASCII
if (typeof bytes.toBase64 !== "function") {
console.log("Uint8Array.prototype.toBase64 is not available on this JavaScript engine",
"(see the comment at the top of this file)");
} else {
// ------------------------------------------------------------------------
// 1) codificação em base64
// ------------------------------------------------------------------------
const inBase64 = bytes.toBase64();
console.log("bytes in base64 =", inBase64);
// decodificação: reconstruir um Uint8Array a partir de uma string base64
const recoveredBytes = Uint8Array.fromBase64(inBase64);
console.log("recovered bytes =", recoveredBytes);
console.log("identical to the original :", bytes.toString() === recoveredBytes.toString());
// ------------------------------------------------------------------------
// 2) codificação hexadecimal
// ------------------------------------------------------------------------
const inHexadecimal = bytes.toHex();
console.log("bytes in hexadecimal =", inHexadecimal);
const bytesFromHex = Uint8Array.fromHex(inHexadecimal);
console.log("bytes from hex =", bytesFromHex);
// ------------------------------------------------------------------------
// 3) preenchimento de um Uint8Array existente, a partir de um deslocamento dado
// ------------------------------------------------------------------------
// útil para montar várias partes no mesmo buffer, sem alocações
// intermediárias
const buffer = new Uint8Array(10);
const writeResult = buffer.setFromHex("48656c6c6f"); // "Hello" em hexadecimal
console.log("buffer after setFromHex =", buffer);
console.log("characters read / written =", writeResult);
}
// ------------------------------------------------------------------------
// por que é útil: transmitir dados binários em formatos de texto
// (JSON, URL, cabeçalhos HTTP...), sem depender de um pacote de terceiros nem de gambiarras
// ------------------------------------------------------------------------
|
npx tsx ecmascript-2026/05-uint8array-base64-hex.ts
Resultado da execução:
| bytes in base64 = SGVsbG8=
recovered bytes = Uint8Array(5) [ 72, 101, 108, 108, 111 ]
identical to the original : true
bytes in hexadecimal = 48656c6c6f
bytes from hex = Uint8Array(5) [ 72, 101, 108, 108, 111 ]
buffer after setFromHex = Uint8Array(10) [
72, 101, 108, 108, 111,
0, 0, 0, 0, 0
]
characters read / written = { read: 10, written: 5 }
|
3.12.7. script [06-json-rawJSON-and-reviver]
Este último script difere dos anteriores: [JSON.rawJSON]/[isRawJSON], assim como o novo parâmetro "context" no reviver de JSON.parse, já funcionam com o Node 22 (as saídas deste capítulo foram obtidas com o Node 26):
| 'use strict';
// ========================================================================
// [NOVO ECMAScript 2026] JSON.rawJSON / JSON.isRawJSON, e o contexto do reviver
// ========================================================================
// [estes dois novos recursos já funcionam com o node 22, diferentemente dos outros
// scripts desta pasta, que exigem o node 24 - veja ecmascript-2026/README.md]
// ------------------------------------------------------------------------
// 1) o problema: JSON.stringify perde precisão em inteiros grandes
// ------------------------------------------------------------------------
// um number JavaScript clássico (tipo [number]) não consegue representar
// exatamente os inteiros além de Number.MAX_SAFE_INTEGER (cf. basics/basics-09.ts)
// no entanto, muitas APIs (bancos de dados, redes sociais, ...) enviam
// identificadores numéricos de 17 a 19 dígitos em seu JSON
const databaseColumnIdentifier = "9007199254740993123"; // grande demais para um [number]
interface DataRecord {
id: unknown; // desconhecido aqui porque será um RawJSON ou um valor normal
name: string;
}
// ------------------------------------------------------------------------
// 2) JSON.rawJSON(): insere um número "bruto" em um JSON.stringify,
// sem nunca passá-lo pelo tipo [number] (portanto sem perda de precisão)
// ------------------------------------------------------------------------
const record: DataRecord = {
id: JSON.rawJSON(databaseColumnIdentifier),
name: "temperature-sensor-3"
};
const jsonText = JSON.stringify(record);
console.log("jsonText =", jsonText);
// o identificador aparece como está no texto produzido, dígito por dígito,
// enquanto um id: Number(databaseColumnIdentifier) teria sido arredondado
// JSON.isRawJSON() permite verificar se um valor foi criado por JSON.rawJSON
console.log("JSON.isRawJSON(record.id) =", JSON.isRawJSON(record.id));
// ------------------------------------------------------------------------
// 3) o reviver de JSON.parse agora recebe um 3º parâmetro [context]
// ------------------------------------------------------------------------
// antes de 2026, o reviver só recebia (key, value): impossível saber
// qual era o texto JSON EXATO de onde vinha esse valor (útil justamente
// para recuperar um número grande sem perda, mantendo-o como texto)
const reReadObject = JSON.parse(jsonText, (key, value, context) => {
// [context.source] fornece o texto JSON bruto correspondente a este valor,
// antes de qualquer conversão para um tipo JavaScript - undefined para objetos/arrays
if (context?.source !== undefined) {
console.log(`key="${key}", converted value=${value}, original JSON text="${context.source}"`);
}
return value;
});
console.log("reReadObject =", reReadObject);
|
- [JSON.rawJSON(text)] insere um número “bruto” em JSON.stringify sem nunca convertê-lo para o tipo
number — útil para identificadores numéricos muito grandes (além de Number.MAX_SAFE_INTEGER, veja basics-09), que de outra forma perderiam precisão;
- o terceiro parâmetro,
context, da função reviver dá acesso, por meio de context.source, ao texto JSON bruto do valor que está sendo processado — antes de qualquer conversão para um tipo JavaScript.
npx tsx ecmascript-2026/06-json-rawJSON-and-reviver.ts
Resultado da execução:
| jsonText = {"id":9007199254740993123,"name":"temperature-sensor-3"}
JSON.isRawJSON(record.id) = true
key="id", converted value=9007199254740993000, original JSON text="9007199254740993123"
key="name", converted value=temperature-sensor-3, original JSON text=""temperature-sensor-3""
reReadObject = { id: 9007199254740993000, name: 'temperature-sensor-3' }
|
Vemos claramente o benefício de JSON.rawJSON: o texto JSON resultante preserva o identificador dígito a dígito (9007199254740993123), enquanto um simples id: Number(...) o teria arredondado — como demonstra o valor retornado por JSON.parse (9007199254740993000), que foi de fato convertido para o tipo number e perdeu precisão.
3.13. Temporal: o substituto moderno de Date
[Temporal] é um novo namespace global destinado a substituir o antigo objeto Date, há muito considerado falho: mutabilidade, meses numerados de 0 a 11, falta de tratamento real de fusos horários e interpretação ambígua de strings. Date não foi removido da linguagem — o código existente continua funcionando —, mas Temporal é agora a abordagem recomendada para qualquer código novo que manipule datas, horas e durações.
3.13.1. ⚠️ Situação exata em relação ao ECMAScript 2026
A proposta Temporal chegou ao estágio 4 do TC39 em março de 2026, e numerosos artigos a apresentaram como parte do ECMAScript 2026. No entanto, a seção oficial da especificação que resume o conteúdo do ECMAScript 2026 (citada no capítulo anterior) não a menciona explicitamente — a questão ainda precisa ser esclarecida. Na prática, Temporal está disponível nativamente no Node.js 26 e em navegadores atualizados, o que torna este capítulo relevante desde já.
Os scripts a seguir estão na pasta [temporal]:

3.13.2. script [01-plainDate-plainTime-plainDateTime]
Este script demonstra [Temporal.PlainDate] (uma data sem hora nem fuso horário), [Temporal.PlainTime] (uma hora sem data) e [Temporal.PlainDateTime] (data + hora, sem fuso horário):
| 'use strict';
// ========================================================================
// [NOVO ECMAScript 2026] Temporal: PlainDate, PlainTime, PlainDateTime
// ========================================================================
// [requer Node 26+ - veja temporal/README.md]
// [Temporal] é um namespace novinho em folha, projetado para substituir [Date],
// que sofria de várias falhas: mutabilidade, meses numerados de 0 a 11
// (janeiro = 0!), nenhum tratamento real de fuso horário e um
// único objeto que deveria representar ao mesmo tempo uma data, uma hora E um instante.
// Temporal separa claramente essas noções em vários tipos.
// ------------------------------------------------------------------------
// 1) Temporal.PlainDate: uma data SEM hora nem fuso horário
// ------------------------------------------------------------------------
// útil para: um aniversário, um prazo, um feriado...
// noções que não têm um "momento preciso do dia"
const birthday = Temporal.PlainDate.from("2026-08-24");
console.log("birthday =", birthday.toString());
console.log("year =", birthday.year, ", month =", birthday.month, ", day =", birthday.day);
// diferentemente do antigo Date, o mês é numerado normalmente: 8 = agosto (não 7!)
console.log("day of the week (1=Monday..7=Sunday) =", birthday.dayOfWeek);
console.log("number of days in this month =", birthday.daysInMonth);
// ------------------------------------------------------------------------
// 2) imutabilidade: add() e subtract() retornam um NOVO objeto
// ------------------------------------------------------------------------
// com o antigo Date, date.setDate(date.getDate() + 7) modifica o objeto no próprio local -
// uma fonte clássica de bugs quando esse objeto é compartilhado em outro ponto do código
const inOneWeek = birthday.add({ days: 7 });
console.log("birthday (unchanged) =", birthday.toString());
console.log("inOneWeek (new object) =", inOneWeek.toString());
// aritmética com meses: trata automaticamente o número de dias do mês seguinte
const endOfJanuary = Temporal.PlainDate.from("2026-01-31");
const oneMonthLater = endOfJanuary.add({ months: 1 });
console.log("endOfJanuary =", endOfJanuary.toString(), ", +1 month =", oneMonthLater.toString());
// -> "2026-02-28" e não um estranho estouro para março, diferentemente do antigo Date
// ------------------------------------------------------------------------
// 3) comparação de duas datas
// ------------------------------------------------------------------------
const backToSchool = Temporal.PlainDate.from("2026-09-01");
console.log("birthday before back to school :", Temporal.PlainDate.compare(birthday, backToSchool) < 0);
console.log("equality :", birthday.equals("2026-08-24"));
// duração entre duas datas
const duration = birthday.until(backToSchool);
console.log("duration until back to school =", duration.toString());
// ------------------------------------------------------------------------
// 4) Temporal.PlainTime: uma hora SEM data nem fuso horário
// ------------------------------------------------------------------------
// útil para: "a aula começa às 14h30", independentemente do dia
const classTime = Temporal.PlainTime.from("14:30:00");
console.log("classTime =", classTime.toString());
const endOfClass = classTime.add({ hours: 1, minutes: 30 });
console.log("endOfClass =", endOfClass.toString());
// ------------------------------------------------------------------------
// 5) Temporal.PlainDateTime: data + hora, mas SEM fuso horário
// ------------------------------------------------------------------------
// útil para: um compromisso "civil" sem se preocupar com o fuso horário (ex.: um formulário
// que apenas exibe "24/08/2026 14:30" sem especificar onde)
const appointment = Temporal.PlainDateTime.from("2026-08-24T14:30:00");
console.log("appointment =", appointment.toString());
// podemos extrair a parte da data e a parte da hora separadamente
console.log("date part =", appointment.toPlainDate().toString());
console.log("time part =", appointment.toPlainTime().toString());
|
- Ao contrário do antigo objeto Date, o mês em Temporal.PlainDate é numerado normalmente: 8 corresponde a agosto, não a julho;
- [immutability]: add() e subtract() sempre retornam um novo objeto — o original nunca é modificado, ao contrário de Date.prototype.setDate;
- as operações aritméticas com meses tratam automaticamente os diferentes comprimentos dos meses (31 de janeiro + 1 mês resulta de fato em 28 de fevereiro, e não em um transbordamento para março);
- Temporal.PlainDate.compare(...) e .until(...) permitem comparar duas datas e calcular a duração entre elas.
3.13.3. script [02-zonedDateTime]
[Temporal.ZonedDateTime] é o tipo mais parecido com o antigo Date: combina data, hora e fuso horário de forma confiável e explícita:
| 'use strict';
// ========================================================================
// [NOVO ECMAScript 2026] Temporal.ZonedDateTime: o verdadeiro substituto de Date
// ========================================================================
// [requer Node 26+ - veja temporal/README.md]
// [Temporal.ZonedDateTime] é o tipo mais próximo do antigo [Date]:
// combina uma data, uma hora E um fuso horário - mas de forma confiável
// e explícita, enquanto [Date] tratava isso de maneira confusa e implícita.
// ------------------------------------------------------------------------
// 1) criação de um ZonedDateTime, com um fuso horário EXPLÍCITO
// ------------------------------------------------------------------------
// diferentemente de "new Date('2026-08-24T14:30:00')", que é ambíguo (hora local?
// UTC? depende do formato e do engine JS!), aqui o fuso horário é obrigatório
const parisMeeting = Temporal.ZonedDateTime.from("2026-08-24T14:30:00[Europe/Paris]");
console.log("parisMeeting =", parisMeeting.toString());
console.log("time zone =", parisMeeting.timeZoneId, ", offset =", parisMeeting.offset);
// ------------------------------------------------------------------------
// 2) conversão da mesma reunião para outro fuso horário
// ------------------------------------------------------------------------
// withTimeZone() NÃO altera o instante real, apenas a forma de exibi-lo -
// útil para mostrar o horário do mesmo evento aos participantes do mundo inteiro
const newYorkMeeting = parisMeeting.withTimeZone("America/New_York");
console.log("same meeting, seen from New York =", newYorkMeeting.toString());
const tokyoMeeting = parisMeeting.withTimeZone("Asia/Tokyo");
console.log("same meeting, seen from Tokyo =", tokyoMeeting.toString());
// ------------------------------------------------------------------------
// 3) a aritmética trata automaticamente as mudanças de horário de verão (DST)
// ------------------------------------------------------------------------
// esta é A armadilha clássica do antigo Date: somar "24 horas" nem sempre
// equivale a somar "1 dia" durante uma mudança de horário de verão/inverno
const beforeTimeChange = Temporal.ZonedDateTime.from("2026-10-24T20:00:00[Europe/Paris]");
// somamos um dia "de calendário": o Temporal entende que a mudança de horário deve ser desconsiderada
const oneDayLater = beforeTimeChange.add({ days: 1 });
console.log("before =", beforeTimeChange.toString());
console.log("+ 1 calendar day =", oneDayLater.toString());
// somamos exatamente 24 horas: não é necessariamente a mesma hora local
// se houve uma mudança de horário de verão/inverno no intervalo
const twentyFourHoursLater = beforeTimeChange.add({ hours: 24 });
console.log("+ exactly 24 hours =", twentyFourHoursLater.toString());
// ------------------------------------------------------------------------
// 4) a hora atual, no fuso horário do sistema
// ------------------------------------------------------------------------
const now = Temporal.Now.zonedDateTimeISO();
console.log("now =", now.toString());
console.log("system time zone =", Temporal.Now.timeZoneId());
// ------------------------------------------------------------------------
// 5) comparação e duração entre dois ZonedDateTimes em fusos horários diferentes
// ------------------------------------------------------------------------
const planeDeparture = Temporal.ZonedDateTime.from("2026-12-20T22:00:00[Europe/Paris]");
const planeArrival = Temporal.ZonedDateTime.from("2026-12-21T11:30:00[Asia/Tokyo]");
// o Temporal compara os instantes reais, independentemente do fuso horário exibido de cada lado
const flightDuration = planeDeparture.until(planeArrival);
console.log("flight duration =", flightDuration.toString());
|
- ao contrário de
new Date('2026-08-24T14:30:00'), cuja interpretação (hora local ou UTC) depende do formato exato da string, Temporal.ZonedDateTime.from(...) exige um fuso horário explícito, entre colchetes;
- withTimeZone(...) converte a exibição do mesmo instante real para outro fuso horário sem alterar a hora em si — útil para exibir o horário de uma reunião a participantes de vários países;
- a aritmética trata corretamente as mudanças de horário de verão: somar “1 dia de calendário” nem sempre é o mesmo que somar “exatamente 24 horas” — uma armadilha clássica da antiga função Date.
3.13.4. script [03-duration-and-instant]
[Temporal.Duration] representa um período de tempo (não um momento específico); [Temporal.Instant] representa um ponto específico e universal no tempo — o substituto direto de new Date(...).getTime():
| 'use strict';
// ========================================================================
// [NOVO ECMAScript 2026] Temporal.Duration e Temporal.Instant
// ========================================================================
// [requer Node 26+ - veja temporal/README.md]
// ------------------------------------------------------------------------
// 1) Temporal.Duration: representa um INTERVALO de tempo (não um momento preciso)
// ------------------------------------------------------------------------
// antes, era preciso montar uma duração "na mão" em milissegundos -
// pouco legível e sem distinção entre unidades de calendário (meses, anos)
// e unidades fixas (horas, minutos, segundos)
const tripDuration = Temporal.Duration.from({ hours: 2, minutes: 45 });
console.log("tripDuration =", tripDuration.toString());
console.log("hours =", tripDuration.hours, ", minutes =", tripDuration.minutes);
// uma duração também pode ser criada a partir de sua notação ISO 8601
const worksDuration = Temporal.Duration.from("P3M2W"); // 3 meses e 2 semanas
console.log("worksDuration =", worksDuration.toString());
// total() converte uma duração inteira em uma única unidade
console.log("tripDuration in minutes =", tripDuration.total("minutes"));
// ------------------------------------------------------------------------
// 2) somar uma duração a uma data ou a uma hora
// ------------------------------------------------------------------------
const departure = Temporal.PlainTime.from("08:15:00");
const arrival = departure.add(tripDuration);
console.log("departure =", departure.toString(), ", arrival =", arrival.toString());
// ------------------------------------------------------------------------
// 3) Temporal.Instant: um ponto no tempo PRECISO e UNIVERSAL
// ------------------------------------------------------------------------
// diferentemente de PlainDateTime ou ZonedDateTime (que têm uma noção de calendário
// e de fuso horário), Instant representa apenas "um instante", como um timestamp -
// é o substituto direto de "new Date(something).getTime()"
const now = Temporal.Now.instant();
console.log("now (Instant) =", now.toString());
console.log("epoch in milliseconds =", now.epochMilliseconds);
// um Instant pode ser convertido em um ZonedDateTime em qualquer fuso horário,
// já que um instante preciso corresponde a uma hora local diferente conforme o fuso horário
const nowInParis = now.toZonedDateTimeISO("Europe/Paris");
const nowInSydney = now.toZonedDateTimeISO("Australia/Sydney");
console.log("now in Paris =", nowInParis.toString());
console.log("now in Sydney =", nowInSydney.toString());
// ------------------------------------------------------------------------
// 4) duração entre dois instantes e comparação
// ------------------------------------------------------------------------
const start = Temporal.Instant.from("2026-08-24T09:00:00Z");
const end = Temporal.Instant.from("2026-08-24T17:30:00Z");
console.log("duration of the working day =", start.until(end).toString());
console.log("start before end :", Temporal.Instant.compare(start, end) < 0);
|
- Uma
Duration pode ser construída a partir de um objeto ({ hours: 2, minutes: 45 }) ou de uma string no formato ISO 8601 (por exemplo, "P3M2W" para 3 meses e 2 semanas);
- total(unit) converte uma duração inteira em uma única unidade (por exemplo, minutos);
- O mesmo Instant pode ser convertido em ZonedDateTime em qualquer fuso horário — um instante específico corresponde a uma hora local diferente conforme o lugar onde você está.
3.13.5. script [04-comparison-with-Date]
Este script aborda, uma a uma, as falhas históricas de Date mencionadas na introdução e mostra como Temporal as corrige:
| 'use strict';
// ========================================================================
// [NOVO ECMAScript 2026] Temporal vs Date: as armadilhas clássicas corrigidas
// ========================================================================
// [requer Node 26+ - veja temporal/README.md]
// [Date] não foi removido da linguagem (o código existente continua funcionando),
// mas [Temporal] é agora a API recomendada para qualquer código novo.
// este script ilustra, uma a uma, as falhas históricas de [Date].
// ------------------------------------------------------------------------
// armadilha nº 1: meses numerados de 0 a 11 em Date (janeiro = 0!)
// ------------------------------------------------------------------------
const augustDate = new Date(2026, 7, 24); // 7 = agosto?! muito confuso para um iniciante
console.log("[Date] displayed month =", augustDate.getMonth(), "(but it really is the month of August)");
const augustPlainDate = Temporal.PlainDate.from({ year: 2026, month: 8, day: 24 });
console.log("[Temporal] displayed month =", augustPlainDate.month, "(8 = August, as everyone expects)");
// ------------------------------------------------------------------------
// armadilha nº 2: Date é mutável - um objeto compartilhado pode ser modificado por engano
// ------------------------------------------------------------------------
function addOneWeekDate(date: Date): Date {
date.setDate(date.getDate() + 7); // modifica o objeto recebido como parâmetro!
return date;
}
const originalDate = new Date(2026, 7, 24);
const dateWithOneMoreWeek = addOneWeekDate(originalDate);
// armadilha: originalDate também foi modificada, embora isso não fosse necessariamente intencional
console.log("[Date] originalDate after the call =", originalDate.toDateString(), "(modified!)");
console.log("[Date] dateWithOneMoreWeek =", dateWithOneMoreWeek.toDateString());
function addOneWeekTemporal(date: Temporal.PlainDate): Temporal.PlainDate {
return date.add({ days: 7 }); // retorna um NOVO objeto, não modifica nada
}
const originalPlainDate = Temporal.PlainDate.from({ year: 2026, month: 8, day: 24 });
const plainDateWithOneMoreWeek = addOneWeekTemporal(originalPlainDate);
console.log("[Temporal] originalPlainDate after the call =", originalPlainDate.toString(), "(unchanged)");
console.log("[Temporal] plainDateWithOneMoreWeek =", plainDateWithOneMoreWeek.toString());
// ------------------------------------------------------------------------
// armadilha nº 3: o parsing de uma string com Date é ambíguo
// ------------------------------------------------------------------------
// conforme o formato da string, "new Date(...)" a interpreta às vezes como hora local,
// às vezes como UTC - uma armadilha frequente em produção
console.log("[Date] new Date('2026-08-24') =", new Date("2026-08-24").toString(), "(interpreted as UTC)");
console.log("[Date] new Date('2026-08-24 00:00:00') =", new Date("2026-08-24 00:00:00").toString(), "(interpreted as local time)");
// -> as duas linhas acima podem exibir horas diferentes para a "mesma" data!
// com o Temporal, o comportamento é sempre explícito e sem ambiguidade:
// um PlainDate não tem hora alguma, um ZonedDateTime exige um fuso horário preciso
console.log("[Temporal] PlainDate.from('2026-08-24') =", Temporal.PlainDate.from("2026-08-24").toString());
// ------------------------------------------------------------------------
// armadilha nº 4: Date não consegue calcular nativamente uma duração "limpa"
// ------------------------------------------------------------------------
const date1 = new Date(2026, 0, 1);
const date2 = new Date(2026, 7, 24);
const millisecondsBetweenTheTwo = date2.getTime() - date1.getTime();
const daysBetweenTheTwo = millisecondsBetweenTheTwo / (1000 * 60 * 60 * 24);
console.log("[Date] days between the two dates (manual calculation) =", daysBetweenTheTwo);
const p1 = Temporal.PlainDate.from({ year: 2026, month: 1, day: 1 });
const p2 = Temporal.PlainDate.from({ year: 2026, month: 8, day: 24 });
console.log("[Temporal] duration between the two dates =", p1.until(p2).toString());
// ------------------------------------------------------------------------
// em resumo: o Temporal é imutável, sem ambiguidade de fuso horário, com
// tipos separados para cada uso (somente data, somente hora, instante preciso,
// data+hora+fuso...) e aritmética confiável mesmo em torno de mudanças
// de horário de verão e de meses de durações diferentes.
// ------------------------------------------------------------------------
|
- [trap no. 1]: Os meses em
Date são numerados de 0 a 11 (embora new Date(2026, 7, 24) de fato se refira a agosto) — uma fonte comum de confusão para iniciantes;
- [trap no. 2]:
Date é mutável — modificar um objeto Date passado como parâmetro de uma função também modifica o original, o que pode ser surpreendente; Temporal.PlainDate.add() sempre retorna um novo objeto;
- [trap no. 3]: A interpretação de uma string com
new Date(...) é ambígua conforme o formato exato (hora local ou UTC); Temporal é sempre explícito;
- [trap no. 4]: Date não consegue calcular nativamente uma duração “limpa” entre duas datas (é preciso subtrair timestamps em milissegundos e dividir manualmente); Temporal.PlainDate.until(...) faz isso diretamente.