Skip to content

3. Los fundamentos

3.1. Los fundamentos de TypeScript

Nota: En adelante, el término [TypeScript] designará el lenguaje tal como lo define la versión 6, un superconjunto tipado de ECMAScript 2026.

Los scripts de este capítulo se encuentran en la carpeta [basics] del proyecto.

Image

3.1.1. Script [basics-01]

Este script usa el ejemplo introductorio del curso original de JavaScript, traducido y tipado en TypeScript:

/* eslint-disable no-constant-condition */
'use strict';
// esto es un comentario
// constante
const name: string = "dupont";
// una visualización en pantalla
console.log("name : ", name);
// un arreglo con elementos de distintos tipos
// [any] porque este arreglo mezcla deliberadamente varios tipos (demostración)
const array: any[] = ["one", "two", 3, 4];
// su número de elementos
let n: any = array.length;
// un bucle
for (let i = 0; i < n; i++) {
  console.log("array[", i, "] = ", array[i]);
}
// inicialización de 2 variables con el contenido de un arreglo
let [string1, string2]: string[] = ["string1", "string2"];
// concatenación de las 2 cadenas
const string3 = string1 + string2;
// mostrar el resultado
console.log([string1, string2, string3]);
// uso de una función
display(string1);
// se puede conocer el tipo de una variable
displayType("n", n);
displayType("string1", string1);
displayType("array", array);
// el tipo de una variable puede cambiar durante la ejecución
// [n] está tipada como [any] arriba: eso es precisamente lo que permite a TypeScript
// aceptar esta reasignación sobre la marcha, como en JavaScript
n = "has changed";
displayType("n", n);
// una función puede devolver un resultado
let res1: any = f1(4);
console.log("res1=", res1);
// una función puede devolver un arreglo de valores
let res2: any, res3: any;
[res1, res2, res3] = f2();
console.log("(res1,res2,res3)=", [res1, res2, res3]);
// podríamos haber recuperado estos valores en un arreglo
let t: any[] = f2();
for (let i = 0; i < t.length; i++) {
  console.log("t[", i, "]=", t[i]);
}
// algunas pruebas
for (let i = 0; i < t.length; i++) {
  // muestra solo las cadenas
  if (typeof (t[i]) === "string") {
    console.log("t[", i, "]=", t[i]);
  }
}
// operadores de comparación == y ===
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");
}
// otras pruebas
for (let i = 0; i < t.length; i++) {
  // muestra solo los enteros >10
  if (typeof (t[i]) === "number" && Math.floor(t[i]) === t[i] && t[i] > 10) {
    console.log("t[", i, "]=", t[i]);
  }
}
// un bucle 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);

// fin del programa porque ya no hay más código ejecutable

//visualización
//----------------------------------
function display(str: string): void {
  // muestra str
  console.log("string=", str);
}

//displayType
//----------------------------------
function displayType(name: string, variable: unknown): void {
  // muestra el tipo de la variable
  console.log("type[variable ", name, "]=", typeof (variable));
}

//----------------------------------
function f1(param: number): number {
  // suma 10 a param
  return param + 10;
}

//----------------------------------
function f2(): any[] {
  // devuelve 3 valores
  return ["one", 0, 100];
}

Comentemos este código:

  • línea 5: [const name: string = "dupont"] — en TypeScript, se puede anotar explícitamente el tipo de una variable agregando type después de su nombre. Aquí, name tiene garantizado ser una cadena durante todo el programa;
  • línea 10: [const array: any[] = ...] — este arreglo mezcla intencionalmente cadenas y números. El tipo any[] le indica a TypeScript que no verifique los tipos de los elementos: es una elección explícita, distinta de la omisión del tipado (que el modo estricto prohíbe);
  • línea 12: [let n: any = array.length] — n se tipa como any porque, más adelante (línea 32), se le reasigna una cadena después de haberle asignado un número. En JavaScript, una variable puede cambiar de tipo libremente; en TypeScript, esto solo se permite si se autoriza explícitamente con any (o una unión de tipos, como number | string);
  • línea 54: ["2" == (2 as any)] — TypeScript prohíbe, por defecto, comparar dos valores de tipos incompatibles (cadena y número) con ==. La expresión (2 as any) es una aserción de tipo: le decimos explícitamente a TypeScript “trata este valor como any; no verifiques su tipo aquí”, lo que ilustra deliberadamente la coerción de tipos propia del operador ==;
  • línea 93: la función [function displayType(name: string, variable: unknown): void] tipa su segundo parámetro como unknown en lugar de any. A diferencia de any, unknown prohíbe usar el valor sin verificarlo antes; aquí simplemente usamos typeof(variable), que está permitido incluso sobre unknown;
  • líneas 86–108: Las funciones tienen ahora un tipo de retorno explícito (: number, : void..., etc.), escrito después de la lista de parámetros.

Ejecutemos este script:

npx tsx basics/basics-01.ts

Resultado de la ejecución:

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]

El script [basics-02] muestra el uso de las palabras clave [let] y [const]:

'use strict';
// para inicializar una variable se usa let o const
// let para las variables
let x: number = 4;
x++;
console.log(x);
// const para las constantes
const y: number = 10;
x += y;
// prohibido
y++;
  • [let] declara una variable cuyo valor puede cambiar (líneas 4–5);
  • [const] declara una constante cuyo valor no puede cambiar (línea 8);
  • línea 11: se intenta reasignar la constante y con y++. Aquí es donde TypeScript ofrece una ventaja real sobre JavaScript.

Incluso antes de ejecutar el script, la verificación de tipos señala el error:

npx tsc --noEmit

Resultado de la ejecución:

basics/basics-02.ts(11,1): error TS2588: Cannot assign to 'y' because it is a constant.

En el JavaScript original, este mismo error no se habría detectado hasta el tiempo de ejecución. Ejecutemos de todos modos este script con tsx (que ejecuta el código sin realizar antes la verificación de tipos, a diferencia de tsc) para ver el error tal como lo genera realmente JavaScript:

npx tsx basics/basics-02.ts

Resultado de la ejecución:

1
2
3
5
TypeError: Assignment to constant variable.
    at basics/basics-02.ts:11:1
Importante: tsx transpila TypeScript a JavaScript sin verificación de tipos (como lo hace Babel), para una ejecución rápida durante el desarrollo. Por eso este script se ejecuta (y falla durante la ejecución) aunque no compile con tsc. Para recibir la notificación del error antes de la ejecución, use VSCode (que ejecuta tsc en segundo plano) o el comando `npm run check` .

3.1.3. Script [basics-03]

Ilustra el alcance de las variables globales, que son visibles dentro de una función:

1
2
3
4
5
6
7
8
9
'use strict';
// ámbito de las variables
let count: number = 1;
function doSomething(): void {
  // count es conocida aquí
  console.log("count=", count);
}
// llamada
doSomething();
npx tsx basics/basics-03.ts

Resultado de la ejecución:

count= 1

3.1.4. Script [basics-04]

Una variable local dentro de una función oculta (enmascara) una variable global con el mismo nombre:

'use strict';
// ámbito de las variables
const count: number = 1;
function doSomething(): void {
  // la variable local oculta la variable global
  const count = 2;
  console.log("count inside function=", count);
}
// variable global
console.log("count outside function=", count);
// variable local
doSomething();
npx tsx basics/basics-04.ts

Resultado de la ejecución:

count outside function= 1
count inside function= 2

3.1.5. Script [basics-05]

Una variable local (const count dentro de la función) no es visible fuera de esa función:

'use strict';
// ámbito de las variables
function doSomething(): void {
  // variable local de la función
  const count = 2;
  console.log("count inside function=", count);
}
// aquí count no es conocida
console.log("count outside function=", count);
doSomething();

Aquí también, TypeScript detecta el problema durante la compilación; no es necesario ejecutar el script para saberlo:

npx tsc --noEmit

Resultado de la ejecución:

basics/basics-05.ts(9,40): error TS2304: Cannot find name 'count'.

Y al ejecutarlo con tsx:

npx tsx basics/basics-05.ts

Resultado de la ejecución:

ReferenceError: count is not defined
    at basics/basics-05.ts:9:40

3.1.6. Script [basics-06]

Este script compara el ámbito de bloque ([let], [const]) con la ausencia de ámbito de bloque ([var]):

'use strict';
// la palabra clave [let] define una variable con ámbito de bloque
{
  // la variable [count] solo es conocida en este bloque
  let count: number = 1;
  console.log("count=", count);
}
// aquí la variable [count] no es conocida
count++;

// la palabra clave [const] define una variable con ámbito de bloque
{
  // la variable [count2] solo es conocida en este bloque
  const count2: number = 1;
  console.log("count=", count2);
}
// aquí la variable [count2] no es conocida
count2++;

// la palabra clave [var] no define una variable con ámbito de bloque
{
  // la variable [count3] será conocida globalmente
  var count3: number = 1;
  console.log("count=", count3);
}
// aquí la variable [count3] es conocida
count3++;
  • Una variable declarada con [let] o [const] dentro de un bloque { } existe solo dentro de ese bloque;
  • una variable declarada con [var] ignora los bloques: sigue siendo visible en toda la función (o script) que la contiene; este era el único comportamiento disponible antes de ECMAScript 2015, lo que fue fuente de numerosos errores, de ahí la recomendación de preferir siempre [let]/[const].

Compilación:

npx tsc --noEmit

Resultado de la ejecución:

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'?

Ejecución (el script se detiene en el primer error encontrado, en count):

npx tsx basics/basics-06.ts

Resultado de la ejecución:

1
2
3
count= 1
ReferenceError: count is not defined
    at basics/basics-06.ts:9:1

3.1.7. Script [basics-07]

Panorama de los principales tipos de TypeScript:

'use strict';

// tipos de datos de 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;
}
// visualización de los 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 }] — un tipo de objeto en línea: la forma esperada del objeto se describe directamente entre llaves, sin necesidad de declarar una interfaz aparte;
  • [var6: () => number] — un tipo función: una función sin parámetros que devuelve un número;
  • en tiempo de ejecución, typeof sigue siendo el de JavaScript (ignora las anotaciones de tipo, que solo existen en tiempo de compilación y desaparecen después): por eso typeof(var4) (un arreglo) y typeof(var5) (un objeto) devuelven ambos "object".
npx tsx basics/basics-07.ts

Resultado de la ejecución:

1
2
3
4
5
6
typeof(var1)= number
typeof(var2)= string
typeof(var3)= boolean
typeof(var4)= object
typeof(var5)= object
typeof(var6)= function

3.1.8. Script [basics-08]

Las conversiones de tipo, tanto implícitas como explícitas, siguen siendo las mismas que en JavaScript (TypeScript no cambia la ejecución):

'use strict';

// cambios de tipo implícitos
// 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 función acepta deliberadamente cualquier tipo como entrada
function showBool(data: any): void {
  // la conversión de los datos a booleano se hace automáticamente en la siguiente prueba
  console.log("[data=", data, "], [type(data)]=", typeof (data), "[boolean value(data)]=", data ? true : false);
}

// cambios de tipo implícitos a un tipo numérico
console.log("---------------[Implicit conversion to a number]------------------------------");
showNumber("12");
showNumber("45.67");
showNumber("abcd");

function showNumber(data: any): void {
  // data + 1 no funciona porque jS hace entonces una concatenación de cadenas en lugar de una suma
  const number = data * 1;
  console.log("[data=", data, "], [type(data)]=", typeof (data), "[number]=", number, "[type(number)]=", typeof (number));
}

// cambios de tipo explícitos a 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 {
  // la conversión de los datos a booleano se hace explícitamente en la siguiente prueba
  console.log("[", data, "], [type(data)]=", typeof (data), "[boolean value(data)]=", Boolean(data));
}
// cambios de tipo explícitos a 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));
}

// a 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));
}

// algunas conversiones implícitas inesperadas
console.log("---------------[Other cases]------------------------------");
const string1: string = '1000.78';
// concatenación de cadenas por defecto
const data1 = string1 + 1.034;
console.log("data1=", data1, "type=", typeof (data1));
const data2 = 1.034 + string1;
console.log("data2=", data2, "type=", typeof (data2));
// conversión explícita a número
const data3 = Number(string1) + 1.034;
console.log("data3=", data3, "type=", typeof (data3));
// true se convierte en el número 1
const data4 = (true as any) * 1.18;
console.log("data4=", data4, "type=", typeof (data4));
// false se convierte en el número 0
const data5 = (false as any) * 1.18;
console.log("data5=", data5, "type=", typeof (data5));
  • Todas las funciones de este script declaran su parámetro data como any: esto es intencional, ya que el objetivo es precisamente mostrar cómo se comporta la misma función con valores de tipos muy distintos (cadena, arreglo, null, undefined, etc.);
  • [Boolean(data)], [Number(data)] y [String(data)] son conversiones explícitas, que siempre son preferibles a las conversiones implícitas, porque son más predecibles y más legibles;
  • último bloque: string1 + 1.034 da como resultado una concatenación de cadenas (el operador + con una cadena a cualquiera de los lados da prioridad a la concatenación), mientras que Number(string1) + 1.034 da como resultado una suma numérica.
npx tsx basics/basics-08.ts

Resultado de la ejecución:

---------------[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]

[NEW since 2019] Este script presenta operadores introducidos en ECMAScript 2020–2021, que hoy se usan con mucha frecuencia:

'use strict';
// ========================================================================
// [NUEVO desde 2019] algunos operadores modernos muy usados a diario
// ========================================================================

// ------------------------------------------------------------------------
// 1) el operador de fusión nula [??]  (ECMAScript 2020)
// ------------------------------------------------------------------------
// con [||], un valor "falsy" (0, "", false, NaN, ...) activa el valor por defecto,
// lo cual no siempre es lo que queremos
const quantity1: number = 0;
console.log("with ||  : quantity1 || 10 =", quantity1 || 10); // -> 10 (¡error! 0 es sin embargo una cantidad válida)
// [??] activa el valor por defecto solo si el valor es null o undefined
console.log("with ??  : quantity1 ?? 10 =", quantity1 ?? 10); // -> 0 (correcto)

const quantity2: number | null = null;
console.log("quantity2 ?? 10 =", quantity2 ?? 10); // -> 10 (quantity2 es null)
const quantity3: number | undefined = undefined;
console.log("quantity3 ?? 10 =", quantity3 ?? 10); // -> 10 (quantity3 es undefined)

// ------------------------------------------------------------------------
// 2) encadenamiento opcional [?.]  (ECMAScript 2020)
// ------------------------------------------------------------------------
// antes de 2020, para acceder de forma segura a una propiedad profunda, había que
// probar cada nivel: if (person && person.address && person.address.city) ...

// interfaz común: [address] es opcional (person2 no tiene una)
interface PersonWithOptionalAddress {
  name: string;
  address?: { city: string };
}

const person1: PersonWithOptionalAddress = {
  name: "Dupont",
  address: {
    city: "Nantes"
  }
};
const person2: PersonWithOptionalAddress = {
  name: "Martin"
  // ¡sin dirección!
};

// [?.] detiene la evaluación y devuelve [undefined] en cuanto un paso es null o undefined
// en lugar de lanzar un error "Cannot read properties of undefined"
console.log("person1 city =", person1.address?.city);
console.log("person2 city =", person2.address?.city); // -> undefined, sin error

// podemos combinar [?.] y [??] para proporcionar un valor de reserva
console.log("person2 city (with default) =", person2.address?.city ?? "unknown city");

// [?.] también funciona en llamadas a métodos...
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, sin error

// ...y en el acceso a un elemento de un arreglo
const arrayOrNull: number[] | null = null;
console.log("element of a missing array :", arrayOrNull?.[0]); // -> undefined

// ------------------------------------------------------------------------
// 3) los operadores de asignación lógica [||=], [&&=], [??=]  (ECMAScript 2021)
// ------------------------------------------------------------------------
// estos operadores combinan una prueba lógica y una asignación en una sola expresión

// [a ??= b] equivale a [a = a ?? b]: asigna b solo si a es null/undefined
interface Configuration {
  delay: number;
  page?: number;
}
const config: Configuration = { delay: 0, page: undefined };
config.delay ??= 1000; // delay ya vale 0 (valor válido) -> permanece sin cambios
config.page ??= 1;     // page es undefined -> pasa a valer 1
console.log("config after ??= :", config);

// [a ||= b] equivale a [a = a || b]: asigna b si a es "falsy" (0, "", null, undefined, false...)
let displayedMessage: string = "";
displayedMessage ||= "default message";
console.log("displayedMessage after ||= :", displayedMessage);

// [a &&= b] equivale a [a = a && b]: asigna b solo si a ya es "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: hace más legibles los números grandes en el código fuente
const oneMillion: number = 1_000_000;
const bankCard: bigint = 1234_5678_9012_3456n; // aquí combinado con un BigInt (ver más abajo)
console.log("oneMillion =", oneMillion);
console.log("bankCard =", bankCard);

// ------------------------------------------------------------------------
// 5) el tipo [BigInt]  (ECMAScript 2020)
// ------------------------------------------------------------------------
// el tipo [number] de JavaScript pierde precisión más allá de aproximadamente 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); // -> mismo resultado que +1, ¡impreciso!

// un [BigInt] se escribe con una [n] final, o se construye con BigInt(...)
const bigNumber1: bigint = 9007199254740993n;
const bigNumber2: bigint = BigInt("9007199254740993");
console.log("bigNumber1 =", bigNumber1, ", type =", typeof (bigNumber1));
console.log("bigNumber1 === bigNumber2 :", bigNumber1 === bigNumber2);
// un BigInt y un number no se pueden mezclar directamente en un cálculo
try {
  console.log((bigNumber1 as any) + 1); // provoca un error [TypeError]
} catch (error: any) {
  console.log("expected error :", error.message);
}
// se necesita una conversión explícita
console.log("bigNumber1 + 1n =", bigNumber1 + 1n);

Veamos las novedades más importantes:

  • [??], coalescencia nula (ECMAScript 2020): a diferencia de [||], que devuelve su valor predeterminado para cualquier valor “falso” (0, "", false...), [??] se activa solo si el valor es null o undefined. Es la elección correcta para una cantidad que puede ser legítimamente 0;
  • [?.], encadenamiento opcional (ECMAScript 2020): detiene la evaluación y devuelve undefined en cuanto un paso intermedio es null o undefined, en lugar de lanzar un error. Funciona también en llamadas a métodos (object.method?.()) y en la indexación (array?.[0]);
  • [||=], [&&=], [??=], operadores de asignación lógica (ECMAScript 2021): combinan una prueba lógica y una asignación en una sola expresión (a ??= b equivale a a = a ?? b);
  • los separadores numéricos 1_000_000 (ECMAScript 2021): puramente visuales, hacen más legibles los números grandes en el código fuente;
  • el tipo [BigInt] (ECMAScript 2020), que se denota con una “n” final (9007199254740993n): a diferencia de number, no pierde precisión más allá de Number.MAX\_SAFE\_INTEGER. Un BigInt y un number no pueden mezclarse directamente en un cálculo, como lo muestra el bloque try/catch del script.
npx tsx basics/basics-09.ts

Resultado de la ejecución:

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. Conclusión

Hemos recorrido los fundamentos del sistema de tipos de TypeScript: anotaciones de tipo en variables, parámetros de funciones y valores de retorno; los tipos any y unknown ; los principales operadores modernos del lenguaje (??, ?., ||=/&&=/??=); y el tipo BigInt . El siguiente capítulo trata los arreglos.

3.2. Arreglos

Los scripts de este capítulo se encuentran en la carpeta [arrays] del proyecto:

Image

3.2.1. Script [arr-01]

El siguiente script ilustra una característica clave de los arreglos de TypeScript/JavaScript: son objetos manipulados por referencia (mediante un puntero), y no datos que se copian en cada asignación.

'use strict';

// un arreglo es un objeto que se maneja mediante su dirección
const arr1: number[] = [1, 2, 3];
// copia de direcciones
const arr2: number[] = arr1;
// arr1 y arr2 apuntan al mismo arreglo
console.log("arr1===arr2 :", arr1 === arr2);
// el arreglo se puede modificar a través de arr1 o de arr2
arr2[1] = 10;
console.log("arr1=", arr1);
console.log("arr2=", arr2);
npx tsx arrays/arr-01.ts

Resultado de la ejecución:

1
2
3
arr1===arr2 : true
arr1= [ 1, 10, 3 ]
arr2= [ 1, 10, 3 ]
  • arr1===arr2 se evalúa como true: ambas variables apuntan al mismo arreglo en memoria;
  • por lo tanto, modificar el arreglo a través de arr2 también modifica lo que se ve a través de arr1; esta es una consecuencia directa de que arr1 y arr2 hacen referencia a los mismos datos.

3.2.2. Script [arr-02]

Este script muestra que el arreglo de TypeScript no tiene un tamaño fijo y se comporta más como una lista indexada dinámica que como un arreglo tradicional de un lenguaje compilado:

'use strict';

// arreglo
// [any] porque este arreglo contendrá huecos y valores de distintos tipos
const arr: any[] = [];
console.log("arr=", arr, ", length=[", arr.length, "]");
console.log("-------------------------------");
// inicialización de un elemento
arr[3] = 100;
arr[1] = "eight";
// arreglo
console.log("arr=", arr, ", length=[", arr.length, "]");
console.log("-------------------------------");
// toString
console.log("arr.toString=[", arr.toString(), "]");
console.log("-------------------------------");
// las claves del arreglo son sus índices
for (let key of arr.keys()) {
  console.log("key=[", key, "], value=[", arr[key], "]");
}
console.log("-------------------------------");
// los valores del arreglo
for (let value of arr.values()) {
  console.log("value=[", value, "]");
}
  • línea 5: const arr: any[] = [] — un arreglo vacío, tipado como any[] porque contendrá intencionalmente “huecos”;
  • líneas 9–10: el elemento n.º 3 puede inicializarse aunque los elementos 0, 1 y 2 aún no existan; se convierten en “huecos” (empty items), que son distintos de undefined aunque a menudo se muestren de forma similar;
  • líneas 18–20: los métodos keys() y values() devuelven iteradores que pueden recorrerse con for...of.
npx tsx arrays/arr-02.ts

Resultado de la ejecución:

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 muestra los principales métodos para manipular un arreglo: recorrerlo, agregar y eliminar elementos.

'use strict';
// un arreglo puede contener datos de distintos tipos
// [any] porque este arreglo mezcla deliberadamente varios tipos (demostración)
const arr: any[] = [1, 2, "one", "two", true, [10, 20], { prop1: 10, prop2: "abc" }];
// console.log puede mostrar el contenido de un arreglo
show(1);
console.log("arr=", arr);
show(2);
// recorrido del arreglo con foreach
arr.forEach(element => {
  console.log("element=", element, typeof (element));
});
show("2b");
// otra sintaxis para hacer lo mismo
arr.forEach(function (element) {
  console.log("element=", element, typeof (element));
});
show(3);
// recorrido del arreglo con for
for (let i = 0; i < arr.length; i++) {
  console.log("i=", i, "arr[i]=", arr[i]);
}
show(4);
// modificación de arr[i]
arr[5] = [];
// visualización
console.log("arr=", arr);
show(5);
// eliminamos el último elemento del arreglo
let element = arr.pop();
console.log("element=", element, "arr=", arr);
show(6);
// agregamos un elemento al final del arreglo
arr.push('xyz');
console.log("arr=", arr);
show(7);
// agregamos un elemento al inicio del arreglo
arr.unshift(1000);
console.log("arr=", arr);
show(8);
// eliminamos el 1.er elemento
element = arr.shift();
console.log("element=", element, "arr=", arr);
show(9);
// eliminamos el elemento n.º 2 del arreglo
element = arr.splice(2, 1);
console.log("element=", element, "arr=", arr);
show(10);
// eliminamos dos elementos del arreglo a partir del elemento n.º 1
element = arr.splice(1, 2);
console.log("element=", element, "arr=", arr);

// función
function show(param: number | string): void {
  console.log("[", param, ":::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ]");
}
  • Línea 4: Aunque arr se declara como const, su contenido puede modificarse (línea 25, arr[5] = []). Lo constante es el puntero al arreglo, no el arreglo en sí;
  • líneas 10–12: forEach recorre el arreglo y llama a la función pasada como parámetro para cada elemento; aquí está escrita con la notación de flecha: element => { ... };
  • líneas 15–17: lo mismo, escrito con la sintaxis tradicional de function; las dos formas son equivalentes;
  • Los métodos pop(), push(), unshift(), shift() y splice() modifican el arreglo in situ (tienen efectos secundarios): esta es una diferencia importante con los métodos “inmutables” vistos en el script arr-05.
npx tsx arrays/arr-03.ts

Resultado de la ejecución (formateado en una sola línea para facilitar la lectura):

[ 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 presenta los métodos funcionales para transformar un arreglo: map, reduce, filter, find, findIndex, indexOf, sort.

'use strict';

// métodos de manipulación de arreglos

// un arreglo
const arr: number[] = [];
for (let i = 0; i < 10; i++) {
  arr[i] = i * 10;
}
// visualización
console.log("arr=", arr);
// map
const arr2 = arr.map(element => {
  return { prop1: element, prop2: element * element }
});
// visualización
console.log("arr=", arr);
console.log("arr2=", arr2);
// reduce sin valor inicial
const sum = arr.reduce((accumulator, currentValue) => accumulator + currentValue);
console.log("sum arr=", sum);
// reduce con 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);
// ordenación inversa
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 y devuelve un nuevo arreglo; el original permanece sin cambios;
  • [reduce] “acumula” los elementos uno por uno en un único resultado. El primer parámetro de su función (accumulator) es el resultado acumulado hasta el momento; el segundo (currentValue) es el elemento actual. Sin un valor inicial (línea 20), el acumulador comienza con el primer elemento del arreglo;
  • [filter] conserva solo los elementos para los que la función devuelve un valor “verdadero”;
  • [find] devuelve el primer elemento que cumple el criterio (o undefined), mientras que [findIndex] devuelve su índice (o -1);
  • [sort] sin parámetros ordena en orden natural. Con una función de comparación (e1, e2) => ..., se tiene control total sobre el orden: -1 si e1 debe ir antes que e2, +1 en caso contrario y 0 en caso de empate.
npx tsx arrays/arr-04.ts

Resultado de la ejecución:

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]

[NEW since 2019] Este script muestra los nuevos métodos de arreglos introducidos entre 2022 y 2023:

'use strict';
// ========================================================================
// [NUEVO desde 2019] nuevos métodos de arreglos
// ========================================================================

// ------------------------------------------------------------------------
// 1) at(index)  (ECMAScript 2022)
// ------------------------------------------------------------------------
// antes, para acceder al último elemento de un arreglo, escribíamos arr[arr.length - 1]
const arr: number[] = [10, 20, 30, 40, 50];
console.log("arr[arr.length - 1] =", arr[arr.length - 1]); // forma antigua
console.log("arr.at(-1) =", arr.at(-1)); // -> último elemento, más legible
console.log("arr.at(-2) =", arr.at(-2)); // -> penúltimo elemento
console.log("arr.at(0)  =", arr.at(0));  // -> equivale a arr[0]
// .at también funciona con cadenas de caracteres
console.log("'hello'.at(-1) =", "hello".at(-1));

// ------------------------------------------------------------------------
// 2) findLast() y findLastIndex()  (ECMAScript 2023)
// ------------------------------------------------------------------------
// simétricos de 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) los métodos "inmutables"  (ECMAScript 2023)
// ------------------------------------------------------------------------
// sort(), reverse(), splice() modifican el arreglo original (efecto secundario) - cf. arr-04.js
// sus equivalentes "to..." devuelven un arreglo NUEVO y dejan intacto el original
// [(number | string)[]] porque toSpliced() inserta cadenas en este arreglo más adelante
const original: (number | string)[] = [4, 5, 4, 2];

// toSorted: como sort(), pero sin modificar el original
const sorted = original.toSorted();
console.log("original =", original, " (unchanged)");
console.log("sorted =", sorted);

// toReversed: como reverse(), pero sin modificar el original
const reversed = original.toReversed();
console.log("reversed =", reversed, ", original still =", original);

// toSpliced: como splice(), pero sin modificar el original
// toSpliced(startIndex, countToDelete, ...elementos a insertar)
const modified: (number | string)[] = original.toSpliced(1, 2, "a", "b", "c");
console.log("modified =", modified, ", original still =", original);

// with(index, value): devuelve una copia del arreglo con un solo elemento reemplazado
const replaced = original.with(0, 999);
console.log("replaced =", replaced, ", original still =", original);

// ------------------------------------------------------------------------
// por qué es útil: estos métodos evitan los efectos secundarios, lo cual se
// aprecia particularmente en los frameworks de front-end (React, Angular, Vue...)
// donde a menudo hay que producir un nuevo estado sin modificar el anterior.
// ------------------------------------------------------------------------
  • [at(index)] (ES2022): acceso seguro y legible, incluso con índices negativos (at(-1) = último elemento), más legible que arr[arr.length - 1];
  • [findLast]/[findLastIndex] (ES2023): igual que find/findIndex, pero devuelve el último elemento que cumple la condición;
  • [toSorted], [toReversed], [toSpliced], [with] (ES2023): los equivalentes inmutables de sort, reverse, splice y de la asignación indexada; devuelven un arreglo nuevo sin modificar el original, a diferencia de los métodos del script arr-03. Muy útiles en los frameworks de front-end (React, Vue...), donde hay que producir un nuevo estado sin modificar el anterior.
npx tsx arrays/arr-05.ts

Resultado de la ejecución:

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. Conclusión

Lo esencial de este capítulo es que un arreglo es un objeto referenciado mediante un puntero, sin tamaño fijo y dotado de un amplio conjunto de métodos; algunos modifican el arreglo in situ (push, sort…), mientras que otros, más recientes, devuelven siempre un arreglo nuevo (toSorted, with…). El siguiente capítulo trata los objetos literales.

3.3. Objetos literales

Aquí llamamos “objetos literales” a los objetos definidos directamente en el código, en contraposición a las instancias de [class] (tratadas en el capítulo “Clases”). Los scripts de este capítulo se encuentran en la carpeta [objects] del proyecto:

Image

3.3.1. Script [obj-01]

Al igual que con los arreglos, se accede a un objeto mediante un puntero. En TypeScript, además, hay que definir la estructura del objeto mediante una interfaz antes de poder agregarle propiedades dinámicamente.

'use strict';
// un objeto vacío
// interface: anunciamos de antemano las propiedades que vamos a agregar dinámicamente,
// porque TypeScript (a diferencia de JavaScript) exige conocer la forma de un objeto
interface Obj1 {
  prop1?: string;
  prop2?: number[];
  prop3?: boolean;
  [key: string]: unknown;
}
const obj1: Obj1 = {};
// las propiedades del objeto se pueden crear dinámicamente
obj1.prop1 = "abcd";
console.log('obj1=', obj1);
// otra propiedad
obj1.prop2 = [1, 2, 3];
console.log("obj1=", obj1);
// otra propiedad con una notación diferente
obj1['prop3'] = true;
console.log("obj1=", obj1);
// obj1 es una referencia al objeto (puntero), no el objeto en sí
const obj2: Obj1 = obj1;
// obj2 y obj1 apuntan al mismo objeto
obj2.prop1 = "xyzt";
console.log("obj1=", obj1);
console.log("obj2=", obj2);
// las propiedades pueden ser variables
const var1: string = 'prop1';
console.log('prop1=', obj1[var1]);
  • Líneas 5–9: [interface] Obj1 declara de antemano las propiedades que se agregarán (prop1, prop2, prop3, todas opcionales con ?). La línea [key: string]: unknown es una firma de índice: permite además agregar cualquier otra propiedad no especificada de antemano;
  • línea 19: obj1.prop3 también puede escribirse como obj1['prop3']; esta notación es indispensable cuando el nombre de la propiedad es en realidad el valor de una variable (líneas 28–29);
  • líneas 22–25: const obj2: Obj1 = obj1 es una copia de referencia, no una copia del objeto; por lo tanto, modificar obj2 también modifica lo que se ve a través de obj1, igual que con los arreglos.
npx tsx objects/obj-01.ts

Resultado de la ejecución:

1
2
3
4
5
6
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 muestra un objeto de varios niveles e introduce el objeto global [JSON], que convierte un objeto en cadena y viceversa.

'use strict';
// un objeto de varios niveles
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
  }
}
// acceso a las propiedades
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 puede mostrar objetos
console.log("person=", person);
console.log("mother=", person.mother);
// también podemos mostrar la cadena jSON del objeto
let json: string = JSON.stringify(person);
console.log("jSON=", json);
// podemos volver a leer el jSON
let person2: PersonWithFamily = JSON.parse(json);
console.log("father=", person2.father);
  • Líneas 3–8: Una [interface] puede contener a su vez tipos de objeto anidados (father, mother);
  • línea 30: [JSON.stringify] convierte un objeto de TypeScript en una cadena JSON;
  • línea 33: [JSON.parse] hace lo contrario; observe que el resultado es de tipo PersonWithFamily, lo que implica que la cadena JSON se ajusta efectivamente a este formato (TypeScript no lo verifica en tiempo de ejecución, solo en tiempo de compilación).
npx tsx objects/obj-02.ts

Resultado de la ejecución:

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 introduce el concepto de getters y setters para una propiedad de un objeto:

'use strict';
// getters y setters de un 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);
// el objeto mismo
console.log("person=", person);
// esto no impide acceder directamente a la propiedad [_name]
person._name = "xyz";
console.log("person=", person);
  • Líneas 3–6: la [interface] PersonWithName declara _name como una propiedad opcional (prefijada con un guion bajo por convención, para indicar que es una propiedad “privada”, aunque TypeScript no impide el acceso a ella; véase el encapsulamiento verdadero con #field en el capítulo “Clases”);
  • líneas 8–11: [getter]—que usa la palabra clave get en lugar de una función— devuelve el valor de _name;
  • líneas 13–16: [setter]—que usa la palabra clave set— recibe el valor asignado y puede validarlo antes de almacenarlo;
  • línea 20: person.name = "Hercule" llama implícitamente al setter;
  • línea 22: person.name llama implícitamente al getter;
  • línea 26: nada impide el acceso directo a _name; el encapsulamiento por convención depende de la disciplina del desarrollador.
npx tsx objects/obj-03.ts

Resultado de la ejecución:

1
2
3
4
5
name setter
name getter
Hercule
person= { name: [Getter/Setter], _name: 'Hercule' }
person= { name: [Getter/Setter], _name: 'xyz' }

Observe que [console.log] muestra [Getter/Setter] para indicar que "name" se gestiona mediante accesores y no es un valor directo.

3.3.4. Script [obj-04]

Tres formas de escribir el nombre de una propiedad, dos formas de acceder a ella y una notación abreviada:

'use strict';
// los nombres de las propiedades de un objeto pueden ser literales [name], entre apóstrofos ['name']
// o entre comillas ["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 comillas
const obj3: FullName = {
  "lastName": "martin",
  "firstName": "jean"
};

// dos sintaxis posibles para acceder a la propiedad [lastName]
console.log("lastName=", obj3.lastName);
console.log("lastName=", obj3['lastName']);

// notación abreviada equivalente a {obj1:obj1, obj2:obj2}
const obj4 = {
  obj1, obj2
}

console.log("obj4=", obj4)
  • Los nombres de propiedad pueden escribirse literalmente (name:), entre comillas simples ('name':) o entre comillas dobles ("name":); las tres formas son equivalentes;
  • Línea 31: obj3.lastName y obj3['lastName'] acceden a la misma propiedad;
  • Líneas 34–36: const obj4 = { obj1, obj2 } es la notación abreviada de { obj1: obj1, obj2: obj2 }; se usa mucho para agrupar variables existentes en un objeto.
npx tsx objects/obj-04.ts

Resultado de la ejecución:

1
2
3
4
5
6
7
8
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]

Un objeto literal puede tener propiedades de tipo función; esto nos acerca al concepto de clase (propiedades + métodos):

'use strict';

// un objeto puede tener propiedades de tipo [function]
interface PersonWithToString {
  firstName: string;
  age: number;
  father: { firstName: string; age: number };
  mother: { firstName: string; age: number };
  toString: () => string;
}
const person: PersonWithToString = {
  // propiedades
  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());
  • línea 4: [interface] declara toString: () => string; el tipo de un método se declara como el de una propiedad de tipo función;
  • línea 25: dentro del método, [this] hace referencia al propio objeto;this.firstName es la propiedad “firstName” de ese objeto.
npx tsx objects/obj-05.ts

Resultado de la ejecución:

1
2
3
4
5
6
7
8
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 muestra cómo recorrer las propiedades de un objeto sin conocer sus nombres de antemano:

'use strict';

// un objeto puede tener propiedades de tipo [function]
interface PersonWithToString {
  firstName: string;
  age: number;
  father: { firstName: string; age: number };
  mother: { firstName: string; age: number };
  toString: () => string;
  // firma de índice necesaria para permitir el recorrido dinámico con for..in más abajo
  [key: string]: unknown;
}
let person: PersonWithToString = {
  // propiedades
  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);
// propiedades
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 evitar la advertencia de 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 evitar la advertencia de 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);
  }
}
  • Línea 11: La firma de índice [key: string]: unknown es necesaria aquí para que TypeScript permita el acceso dinámico a person[key] desde el bucle for...in;
  • Líneas 35–41: for (const key in person) recorre los nombres de las propiedades. La prueba hasOwnProperty filtra las propiedades heredadas (que no existen en este script, pero es una buena práctica que conviene seguir sistemáticamente);
  • este script ofrece tres formas equivalentes de escribir esta prueba: la segunda (Object.prototype.hasOwnProperty.call(...)) es la más robusta, mientras que la tercera simplemente suprime la advertencia correspondiente de ESLint. Desde 2022, el método Object.hasOwn() (script obj-09, más abajo) ha vuelto innecesaria esta elección.
npx tsx objects/obj-06.ts

Resultado de la ejecución:

{
  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 muestra la desestructuración de objetos, una sintaxis que extrae propiedades directamente en variables:

'use strict';
// desestructuración

interface FullName {
  lastName: string;
  firstName: string;
}

// literal
const obj1: FullName = {
  lastName: "martin",
  firstName: "jean"
};

// desestructuración de obj1 en las variables [n,p]
const { lastName: n, firstName: p } = obj1;
console.log("n=", n, "p=", p);

// desestructuración de obj1 en las variables [n2,p2]
function f({ lastName: n2, firstName: p2 }: FullName): void {
  console.log("f-n2=", n2, "f-p2=", p2);
}
f(obj1);

// desestructuración de obj1 en las variables [lastName,firstName]
function g({ lastName: lastName, firstName: firstName }: FullName): void {
  console.log("g-lastName=", lastName, "g-firstName=", firstName);
}
g(obj1);

// desestructuración de obj1 en las variables [lastName,firstName]
// con notación abreviada equivalente a h({lastName:lastName,firstName:firstName})
function h({ lastName, firstName }: FullName): void {
  console.log("h-lastName=", lastName, "h-firstName=", firstName);
}
h(obj1);
  • línea 16: const { lastName: n, firstName: p } = obj1 crea dos variables n y p, equivalente a const n = obj1.lastName; const p = obj1.firstName;
  • líneas 19–22, 24–27, 30–33: la desestructuración también funciona directamente sobre los parámetros de una función; es muy común en TypeScript/React para extraer propiedades de un objeto de configuración o de props;
  • línea 33: function h({ lastName, firstName }: FullName) es una abreviatura de { lastName: lastName, firstName: firstName }; cuando el nombre de la variable creada es idéntico al nombre de la propiedad, puede omitirse.
npx tsx objects/obj-07.ts

Resultado de la ejecución:

1
2
3
4
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 muestra cómo crear una copia superficial de un objeto con el operador de propagación... :

'use strict'

// clonación de objetos
interface FullName {
  lastName: string;
  firstName: string;
}
const obj1: FullName = {
  lastName: "martin",
  firstName: "jean"
};

// clon de obj1 con el operador spread
const obj2: FullName = { ...obj1 }

// verificaciones
// obj2 apunta a una copia de obj1
console.log("obj2===obj1 :", obj1 === obj2)
console.log("obj2=", obj2)
npx tsx objects/obj-08.ts

Resultado de la ejecución:

obj2===obj1 : false
obj2= { lastName: 'martin', firstName: 'jean' }
  • obj2===obj1 se evalúa como false: las dos referencias no apuntan al mismo objeto;
  • obj2 contiene efectivamente una copia de las propiedades de obj1, pero cuidado: como veremos en el siguiente script, es solo una copia superficial.

3.3.9. Script [obj-09]

[NEW since 2019] Este script muestra tres adiciones útiles introducidas desde 2020: [Object.hasOwn], [structuredClone] y la combinación de encadenamiento opcional con coalescencia nula en objetos anidados.

'use strict';
// ========================================================================
// [NUEVO desde 2019] manipulación de objetos: algunas adiciones útiles
// ========================================================================

// ------------------------------------------------------------------------
// 1) Object.hasOwn(object, property)  (ECMAScript 2022)
// ------------------------------------------------------------------------
// antes, para saber si una propiedad pertenece directamente a un objeto (y no se
// hereda a través de la cadena de prototipos), escribíamos:
//   object.hasOwnProperty(property)               -> puede fallar si el objeto redefine hasOwnProperty
//   Object.prototype.hasOwnProperty.call(object, property)  -> correcto pero verboso (cf. objects/obj-06.js)
// [Object.hasOwn] hace este trabajo de forma simple y sin riesgo
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 en un recorrido de propiedades
console.log("-----------------------");
for (const key in person) {
  if (Object.hasOwn(person, key)) {
    console.log(key, "=", person[key]);
  }
}

// ------------------------------------------------------------------------
// 2) structuredClone(object)  (API global disponible desde node 17)
// ------------------------------------------------------------------------
// obj-08.js muestra la clonación superficial con el operador spread [...obj]
// pero un spread solo clona el 1.er nivel: ¡los subobjetos permanecen compartidos!
interface PersonWithAddress {
  lastName: string;
  address: { city: string; postalCode: string };
}
const original: PersonWithAddress = {
  lastName: "Dupont",
  address: { city: "Nantes", postalCode: "44000" }
};

// clonación superficial con spread
const shallowCopy: PersonWithAddress = { ...original };
shallowCopy.address.city = "Angers"; // ¡también modifica la dirección de [original]!
console.log("shallow copy modified the original :", original.address.city === "Angers");

// reinicio para la siguiente prueba
original.address.city = "Nantes";

// [structuredClone] hace una clonación profunda: todos los subobjetos se copian
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) encadenamiento opcional + fusión nula en métodos de objetos anidados
// ------------------------------------------------------------------------
// combinación muy frecuente en la práctica para leer una configuración parcial
interface AppearanceConfiguration {
  appearance?: { theme?: string };
}
function displayTheme(configuration?: AppearanceConfiguration): void {
  // si falta configuration, configuration.appearance o configuration.appearance.theme,
  // recurrimos a "light" sin fallar nunca
  const theme = configuration?.appearance?.theme ?? "light";
  console.log("theme =", theme);
}
displayTheme({ appearance: { theme: "dark" } });
displayTheme({ appearance: {} });
displayTheme({});
displayTheme(undefined);
  • [Object.hasOwn(object, property)] (ES2022) es un mejor reemplazo de object.hasOwnProperty(...) (véase el script obj-06): es más fácil de leer y nunca presenta problemas si el propio objeto redefine hasOwnProperty;
  • [structuredClone(object)] (disponible de forma nativa desde Node 17) realiza un clon profundo: a diferencia del operador de propagación { ...obj } del script obj-08, que copia solo el primer nivel, structuredClone copia también los subobjetos; modificar la copia nunca modifica el original, en ningún nivel;
  • la función displayTheme combina ?. y ?? para leer una configuración de varios niveles y potencialmente incompleta sin fallar nunca y con un valor de respaldo claro.
npx tsx objects/obj-09.ts

Resultado de la ejecución:

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. Conclusión

Los scripts de este capítulo han mostrado que el objeto literal de TypeScript se parece a una instancia de clase: se pueden definir propiedades, métodos y getters/setters, con la ventaja adicional de una [interface] que describe con precisión su forma en tiempo de compilación. Es un objeto dinámico, comparable a un diccionario, cuyos elementos pueden ser de cualquier tipo, incluidas las funciones.

3.4. Cadenas de caracteres

Los scripts de este capítulo se encuentran en la carpeta [strings] del proyecto:

Image

3.4.1. Script [str-01]

Lo primero que hay que entender es que, una vez creada una cadena, ya no puede modificarse (es inmutable). Existen muchos métodos para crear una cadena nueva a partir de la original, pero la cadena original permanece siempre sin cambios.

'use strict';

// las cadenas de caracteres son de solo lectura (no se pueden modificar)

// una cadena
const string1: string = "abcd ";
// tipo
console.log("typeof(string1)=", typeof (string1));
// carácter n.º 2
console.log("string1[2]=", string1[2]);
// provoca un error
// [actualización de TypeScript] TypeScript detecta el error en tiempo de compilación:
// una cadena solo tiene acceso de lectura por índice
// @ts-expect-error : una cadena de caracteres es de solo lectura
string1[2] = "0";
  • Línea 10: string1[2] lee el tercer carácter de la cadena (índice 0);
  • línea 15: string1[2] = "0" intenta una operación de escritura, que TypeScript rechaza en tiempo de compilación, gracias a @ts-expect-error; el comentario que la precede confirma que este error es esperado y su propósito es precisamente demostrarlo.

Verificación de tipos:

npx tsc --noEmit

Resultado de la ejecución:

strings/str-01.ts(15,1): error TS2540: Cannot assign to '2' because it is a read-only property.

Ejecución con tsx (sin verificación de tipos previa):

npx tsx strings/str-01.ts

Resultado de la ejecución:

1
2
3
4
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]

Una cadena de caracteres puede ser de uno de dos tipos: [string] (cadena literal) u [object] (instancia de la clase [String]):

'use strict';

// las cadenas de caracteres pueden ser de dos tipos

// una cadena literal
const string1: string = "abcd ";
// tipo
console.log("typeof(string1)=", typeof (string1));
// instancia de String
// eslint-disable-next-line @typescript-eslint/ban-types - aquí [String] (objeto) es el tipo exacto buscado, no [string] (primitivo): ese es precisamente el tema de la demostración
const string2: String = new String("xyzt");
// tipo
console.log("typeof(string2)=", typeof (string2));
// otra sintaxis (sin new)
const string3: string = String("12 34");
// tipo
console.log("typeof(string3)=", typeof (string3));
// el tipo [string] y el tipo [object] ofrecen los mismos métodos, los de la clase String
console.log("string1.length=", string1.length);
console.log("string2.length=", string2.length);
  • Línea 6: La forma estándar de definir una cadena; string1 será de tipo string;
  • Línea 11: new String(...) crea un objeto cadena; string2 será de tipo object. Aquí, el tipo declarado en TypeScript es String (con S mayúscula), el tipo del *objeto envoltorio*, que es distinto del tipo primitivo string (en minúscula);
  • Ambos tipos ofrecen los mismos métodos: los de la clase String.
npx tsx strings/str-02.ts

Resultado de la ejecución:

1
2
3
4
5
typeof(string1)= string
typeof(string2)= object
typeof(string3)= string
string1.length= 5
string2.length= 4

3.4.3. Script [str-03]

Este script muestra la interpolación de variables en una cadena:

1
2
3
4
5
6
7
'use strict';

// cadena
const string: string = "Introduction to Javascript by example";
// cadena con interpolación de variables
const str: string = `[${string}].substr(3, 2)=` + string.substr(3, 2)
console.log(str);
  • Línea 6: Una cadena delimitada por acentos graves (*backticks*, AltGr-7 en un teclado francés) puede contener expresiones ${variable} que se reemplazan por el valor de la variable; esto se llama cadena de plantilla.
npx tsx strings/str-03.ts

Resultado de la ejecución:

[Introduction to Javascript by example].substr(3, 2)=ro

3.4.4. Script [str-04]

La cadena de plantilla por sí sola es insuficiente para un formato preciso (ancho, alineación, precisión decimal, etc.). Para ello, se usa un paquete externo, [sprintf-js], que replica las funciones printf/sprintf conocidas de otros lenguajes. Se instala con npm install sprintf-js y puede importarse fácilmente:

1
2
3
4
5
6
7
'use strict';
// uso de un paquete externo para tener la función sprintf
import { sprintf } from 'sprintf-js';
// cadena
const string: string = "Introduction to Javascript by example";
// método
console.log(sprintf("[%s].substr(3,2)=[%s]", string, string.substr(3, 2)));
Contexto: En 2019, la instrucción `import` causaba problemas con Node.js (que aún no admitía de forma nativa los módulos de ECMAScript) y requería un paquete intermedio llamado `esm`. Ya no es así desde Node 12+: nuestro proyecto, con "type": "module" en package.json, usa import/export de forma nativa, sin ninguna configuración adicional.
npx tsx strings/str-04.ts

Resultado de la ejecución:

[Introduction to Javascript by example].substr(3,2)=[ro]

3.4.5. Script [str-05]

La función [sprintf] acepta, como en C, “formatos” introducidos por %: %s (cadena), %d (entero), %f (punto flotante), %j (JSON), %T (tipo), %t (booleano), junto con modificadores de ancho y alineación (%20s, %-20s, %04d...):

'use strict';
// uso de un paquete externo para tener la función sprintf
import { sprintf } from 'sprintf-js';
// cadena
const string: string = "Javascript";
// cadenas de caracteres
console.log(sprintf("[%s, %%s]=>[%s]", string, string));
console.log(sprintf("[%s, %%20s]=>[%20s]", string, string));
console.log(sprintf("[%s, %%-20s]=>[%-20s]", string, string));
// enteros
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));
// reales
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 de la ejecución:

[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 enumera los métodos más comunes de la clase [String]:

'use strict';
// uso de un paquete externo para tener la función sprintf
import { sprintf } from 'sprintf-js';
// cadena
const string: string = "  Introduction to Javascript ";
// algunos métodos
// substr(10,2): 2 caracteres a partir del n.º 10
console.log(sprintf("[%s].substr(10,2)=[%s]", string, string.substr(10, 2)));
// trim: elimina los espacios en blanco al inicio y al final de la cadena (espacio en blanco=\b \t \r \n \f)
console.log(sprintf("[%s].trim()=[%s]", string, string.trim()));
// toLowerCase: conversión a minúsculas
console.log(sprintf("[%s].toLowerCase=[%s]", string, string.toLowerCase()));
// toUpperCase: conversión a mayúsculas
console.log(sprintf("[%s].toUpperCase=[%s]", string, string.toUpperCase()));
// indexOf: posición de una cadena buscada dentro de la cadena, -1 si la subcadena no existe
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 si la cadena buscada está en la cadena
console.log(sprintf("[%s].includes('Java')=[%s]", string, string.includes('Java')));
// length: longitud de la cadena - no es un método sino una propiedad
console.log(sprintf("[%s].length=[%s]", string, string.length));
// slice (7,10): cadena de los caracteres n.º 7 a 9
console.log(sprintf("[%s].slice(7,10)=[%s]", string, string.slice(7, 10)));
// match: busca una expresión en la cadena - esta expresión puede ser una expresión regular
// /intro/i: expresión regular que designa la cadena [intro] en mayúsculas o minúsculas
// devuelve la cadena encontrada
console.log(sprintf("[%s].match(/intro/i)=[%s]", string, string.match(/intro/i)));
// replace: reemplaza string1 por string2 en string
// reemplaza la 1.ª ocurrencia de i por x
console.log(sprintf("[%s].replace('i','x')=[%s]", string, string.replace('i', 'x')));
// reemplaza todas las ocurrencias de i por x
// /i/g es una expresión regular que designa todas (g) las ocurrencias de i
console.log(sprintf("[%s].replace(/i/g,'x')=[%s]", string, string.replace(/i/g, 'x')));
// split: divide la cadena en palabras separadas por el parámetro de split
// devuelve el arreglo de esas palabras
// regex \s* entre barras: palabras separadas por 0 o más espacios
console.log(sprintf("[%s].split(/\\s*/)=[%s]", string, string.split(/\s*/)));
// /\s+/: palabras separadas por uno o más espacios
console.log(sprintf("[%s].split(/\\s+/)=[%s]", string, string.split(/\s+/)));
  • [trim] elimina los espacios en blanco iniciales y finales; [toLowerCase]/[toUpperCase] cambian entre minúsculas y mayúsculas;
  • [indexOf] devuelve la posición de una subcadena (-1 si no está); [includes] devuelve un valor booleano;
  • [slice] extrae una subcadena por posición; [match] compara la cadena con una expresión regular (véase el siguiente capítulo);
  • [replace] reemplaza la primera aparición encontrada (o todas las apariciones, con una expresión regular /g); [split] divide la cadena en un arreglo de palabras.
npx tsx strings/str-06.ts

Resultado de la ejecución:

[  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]

[NEW since 2019] Tres novedades introducidas entre 2020 y 2024: [replaceAll], [matchAll] y la detección y corrección de cadenas “mal formadas”:

'use strict';
// ========================================================================
// [NUEVO desde 2019] nuevos métodos de cadenas de caracteres
// ========================================================================

// ------------------------------------------------------------------------
// 1) replaceAll(search, replace)  (ECMAScript 2021)
// ------------------------------------------------------------------------
// str-06.js muestra que replace() con una cadena solo reemplaza la 1.ª ocurrencia
// y que había que usar una expresión regular /i/g para reemplazar todo
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 también acepta una expresión regular, pero esta debe tener entonces el indicador [g]
console.log("replaceAll with regexp :", string.replaceAll(/cat/g, "dog"));

// ------------------------------------------------------------------------
// 2) matchAll(regexp)  (ECMAScript 2020)
// ------------------------------------------------------------------------
// match() con el indicador [g] solo devuelve las cadenas encontradas, sin su posición ni sus grupos
// matchAll() devuelve un iterador que entrega, para cada ocurrencia, toda la información (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;

// con match (indicador g): perdemos el detalle de los grupos capturados
console.log("match =", text.match(pattern));

// con matchAll: conservamos el detalle (nombre capturado, edad capturada, posición...)
console.log("-----------------------");
for (const result of text.matchAll(pattern)) {
  console.log("name =", result[1], ", age =", result[2], ", position =", result.index);
}

// también podemos convertir el iterador en un arreglo gracias al operador spread
const allResults = [...text.matchAll(pattern)];
console.log("number of matches =", allResults.length);

// ------------------------------------------------------------------------
// 3) isWellFormed() / toWellFormed()  (ECMAScript 2024)
// ------------------------------------------------------------------------
// una cadena JavaScript puede contener un "medio carácter unicode" aislado e inválido
// (por ejemplo cuando una cadena se ha cortado mal). Esto puede hacer que
// algunas funciones fallen (encodeURIComponent, ...)
const validString: string = "café ☕";
const malformedString: string = "abc\uD800def"; // \uD800 es un "medio carácter" aislado, inválido por sí solo

console.log("validString.isWellFormed() =", validString.isWellFormed());
console.log("malformedString.isWellFormed() =", malformedString.isWellFormed());

// toWellFormed() reemplaza los caracteres inválidos por el carácter de reemplazo �
console.log("malformedString.toWellFormed() =", malformedString.toWellFormed());
  • [replaceAll] (ES2021) reemplaza todas las apariciones de una cadena sin requerir una expresión regular /g, como en el script str-06;
  • [matchAll] (ES2020) devuelve un iterador con todos los resultados encontrados, cada uno con sus grupos capturados y su posición (index), mientras que un match con la bandera g devuelve solo las cadenas encontradas, sin ese detalle;
  • [isWellFormed]/[toWellFormed] (ES2024) detectan y corrigen las cadenas que contienen una “mitad de carácter Unicode” aislada (a menudo causada por una división incorrecta de la cadena), lo que puede hacer fallar ciertas funciones, como encodeURIComponent.
npx tsx strings/str-07.ts

Resultado de la ejecución:

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. Expresiones regulares

Los scripts de este capítulo se encuentran en la carpeta [regexp] del proyecto. Tanto en TypeScript como en JavaScript, una expresión regular no es una cadena sino un objeto en sí mismo, de tipo RegExp; por lo tanto, una expresión regular no se encierra entre comillas.

Image

3.5.1. Script [regexp-01]

Este script compara varias cadenas con diferentes patrones (una secuencia de dígitos, una fecha dd/mm/yy, un número decimal) y recupera los grupos coincidentes:

'use strict';

/// expresiones regulares en javascript
// recuperación de los distintos campos de una cadena
// el patrón: una secuencia de dígitos rodeada de cualesquiera caracteres
// solo queremos recuperar la secuencia de dígitos
let pattern: RegExp = /(\d+)/;
console.log("type of a regular expression : ", typeof (pattern));
// comparamos la cadena con el patrón
comparePatternToString(pattern, "xyz1234abcd");
comparePatternToString(pattern, "12 34");
comparePatternToString(pattern, "abcd");

// el patrón: una secuencia de dígitos rodeada de cualesquiera caracteres
// queremos la secuencia de dígitos así como los campos que la siguen y la preceden
pattern = /^(.*?)(\d+)(.*?)$/;
// comparamos la cadena con el patrón
comparePatternToString(pattern, "xyz1234abcd");
comparePatternToString(pattern, "12 34");
comparePatternToString(pattern, "abcd");

// el patrón - una fecha en 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");

// el patrón - un 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 la cadena [str] con el patrón [pattern]
  console.log(`----------- string=${str}, pattern=${pattern}`)
  // comparamos la cadena con el patrón
  const result1 = pattern.exec(str);
  console.log(`comparison with exec=`, result1);
  // otra forma de hacerlo
  const result2 = str.match(pattern);
  console.log(`comparison with match=`, result2);
}
  • línea 7: let pattern: RegExp = /(\d+)/ — el tipo RegExp es explícito aquí, pero TypeScript lo habría deducido automáticamente a partir de la sintaxis /.../ de todos modos;
  • Los métodos [pattern.exec(str)] y [str.match(pattern)] devuelven el mismo resultado: o bien null (sin coincidencia) o un arreglo en el que:
    • el elemento [0] es la cadena completa que coincide con el patrón;
    • los elementos [1], [2]... corresponden a los grupos capturados entre paréntesis, en orden;
    • la propiedad .index devuelve la posición de la coincidencia dentro de la cadena;
    • la propiedad .input devuelve la cadena original.
npx tsx regexp/regexp-01.ts

Resultado de la ejecución:

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]

A veces no se quiere extraer elementos de la cadena evaluada, sino solo saber si coincide con el patrón. En ese caso, se usa [RegExp.test] en lugar de exec/match, y se pueden eliminar los paréntesis de captura, que ya no son necesarios:

'use strict';

/// expresiones regulares en javascript
// recuperación de los distintos campos de una cadena
// el patrón: una secuencia de dígitos rodeada de cualesquiera caracteres
// solo queremos recuperar la secuencia de dígitos
let pattern: RegExp = /\d+/;
console.log("type of a regular expression : ", typeof (pattern));
// comparamos la cadena con el patrón
comparePatternToString(pattern, "xyz1234abcd");
comparePatternToString(pattern, "12 34");
comparePatternToString(pattern, "abcd");

// el patrón: una secuencia de dígitos rodeada de cualesquiera caracteres
// queremos la secuencia de dígitos así como los campos que la siguen y la preceden
pattern = /^.*?\d+.*?$/;
// comparamos la cadena con el patrón
comparePatternToString(pattern, "xyz1234abcd");
comparePatternToString(pattern, "12 34");
comparePatternToString(pattern, "abcd");

// el patrón - una fecha en 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");

// el patrón - un 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 {
  // prueba
  const matches = pattern.test(str);
  // compara la cadena [str] con el patrón [pattern]
  console.log(`----------- string=${str}, pattern=${pattern}, matches=${matches}`);
}
npx tsx regexp/regexp-02.ts

Resultado de la ejecución:

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. Las funciones

Los scripts de este capítulo se encuentran en la carpeta [functions] del proyecto:

Image

3.6.1. Script [func-01]

Este script se centra en cómo se pasan los parámetros a una función: por valor para números, cadenas y booleanos; por referencia para arreglos, objetos literales y funciones.

'use strict';
// cómo se pasan los parámetros de una función
// - - - número - paso por valor
function doSomethingWithNumber(param: number): void {
  param++;
  console.log("[param inside function]=", param, "[type]=", typeof (param), "[pass by reference]=", param === count);
}
// código llamador
let count: number = 10;
doSomethingWithNumber(count);
console.log("[count outside function]=", count);

// - - - cadena - paso 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 llamador
let text: string = "abcd";
doSomethingWithString(text);
console.log("[text outside function]=", text);

// - - - booleano - paso 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 llamador
let bool: boolean = true;
doSomethingWithBoolean(bool);
console.log("bool [outside function]=", bool);

// - - - arreglo - paso por referencia
function doSomethingWithArray(param: number[]): void {
  param.push(1000);
  console.log("[param inside function]=", param, "[type]=", typeof (param), "[pass by reference]=", param === arr);
}
// código llamador
const arr: number[] = [10, 20, 30];
doSomethingWithArray(arr);
console.log("[arr outside function]=", arr);

// - - - objeto - paso por referencia
// [any] para poder agregar dinámicamente [aNewProperty], como en 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 llamador
const obj: any = [10, 20, 30];
doSomethingWithObject(obj);
console.log("[obj outside function]=", obj);

// - - - función - paso por referencia
// [any] porque asignamos dinámicamente una propiedad a la propia función (ver más abajo)
function doSomethingWithFunction(param: any): void {
  // algo bastante extraño que funciona sin embargo
  param.aNewProperty = "xyz";
  console.log("[param inside function]=", param, "[type]=", typeof (param), "[pass by reference]=", param === f);
}
// código llamador
const f: any = (x: number) => x + 4;
doSomethingWithFunction(f);
console.log("[f outside function]=", f, f.aNewProperty, typeof (f));
  • Los tipos primitivos (number, string, boolean) se pasan por valor: modificar param dentro de la función nunca cambia la variable original (pass-by-reference = false en cada caso);
  • los arreglos, objetos y funciones se pasan por referencia: param === arr (o obj, o f) se evalúa como true, y una modificación hecha dentro de la función es claramente visible fuera de ella;
  • línea 45: function doSomethingWithObject(param: any) — tipado como any porque se agrega dinámicamente una propiedad (aNewProperty) no prevista en el tipo original del arreglo obj ;
  • línea 58: lo mismo para doSomethingWithFunction — se agrega una propiedad a la propia función; este comportamiento (de JavaScript) es un poco desconcertante, pero perfectamente válido (una función también es un objeto).
npx tsx functions/func-01.ts

Resultado de la ejecución:

[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 muestra que [function] es un tipo de datos como cualquier otro: una variable puede tener este tipo, y hay dos formas de definir una función: con la palabra clave function o con la notación de flecha =>.

'use strict';
// una función se puede asignar a una variable
const variable1: (a: number, b: number) => number = function (a, b) {
  return a + b;
};
console.log("typeof(variable1)=", typeof (variable1));
// la variable se puede usar entonces como una función
console.log("variable1(10,12)=", variable1(10, 12));
// la función se puede definir con la notación =>
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));
// se pueden omitir las llaves si solo hay una expresión en el código de la función
// esta expresión es entonces el valor de retorno de la función
const variable3 = (a: number, b: number, c: number): number => a + b + c;
console.log("variable3(10,12,14)=", variable3(10, 12, 14));
  • línea 3: const variable1: (a: number, b: number) => number = function (a, b) {...} — el tipo de una variable de función se declara como una firma (parameters) => returnType;
  • líneas 10–12: lo mismo con la notación de flecha (a, b, c) => { ... };
  • línea 16: sin llaves, el cuerpo de la función se reduce a una sola expresión, que se convierte automáticamente en el valor de retorno — (a, b, c): number => a + b + c.
npx tsx functions/func-02.ts

Resultado de la ejecución:

1
2
3
4
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 muestra que una función puede pasarse como argumento a otra función, una técnica muy usada en los frameworks de TypeScript/JavaScript (callbacks, map/filter/reduce del capítulo “Arreglos”...):

'use strict';
// los parámetros de una función pueden ser de tipo [function]

// función f1
function f1(param1: number, param2: number): number {
  return param1 + param2 + 10;
}
// función f2
function f2(param1: number, param2: number): number {
  return param1 + param2 + 20;
}
// función g con una función 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));
// el parámetro real de tipo función se puede pasar directamente - forma 1
console.log(g(0, 10, (param1, param2) => {
  return param1 + param2 + 30;
}));
// el parámetro real de tipo función se puede pasar directamente - forma 2
console.log(g(0, 10, function (param1, param2) {
  return param1 + param2 + 40;
}));
  • línea 13: function g(param1: number, param2: number, f: (a: number, b: number) => number): number — el tercer parámetro, f, está a su vez tipado como una función;
  • líneas 20–22 y 24–26: el parámetro de tipo función real puede pasarse directamente, ya sea como función de flecha o como función normal, sin almacenarlo antes en una variable.
npx tsx functions/func-03.ts

Resultado de la ejecución:

1
2
3
4
120
130
140
150

3.6.4. Script [func-04]

Este script muestra que una función puede comportarse como una clase, un mecanismo anterior a ES6 pero todavía válido, aunque hoy ha sido reemplazado por la palabra clave class (véase el capítulo “Clases”):

'use strict';
// una función se puede usar como un objeto

// una cáscara vacía
// [any]: el tipo de [this] es deliberadamente laxo aquí, porque asignamos
// propiedades a la propia función DESPUÉS de su definición (ver más abajo) -
// un patrón que TypeScript no puede inferir por sí solo
function f(this: any): void {

}
// a la cual asignamos propiedades desde el exterior
(f as any).prop1 = "val1";
(f as any).show = function (this: any) {
  console.log(this.prop1);
};
// uso de f
(f as any).show();

// una función g que funciona como una clase
function g(this: any): void {
  this.prop2 = "val2";
  this.show = function (this: any) {
    console.log(this.prop2);
  };
}
// instanciación de la función con [new]
new (g as any)().show();
  • líneas 5–10: f es una función “cascarón vacío”, tipada con this: any; esta anotación especial en el primer parámetro le indica a TypeScript el tipo dethis` dentro de la función, lo cual es necesario aquí porque se le agregan propiedades desde fuera, un patrón que TypeScript no puede deducir por sí solo;
  • líneas 12–15: se asignan propiedades a f desde fuera — (f as any).prop1 = ...;
  • Línea 17: Llamamos a f.show(), no a f(); esta es, en efecto, la notación para usar un objeto, no una llamada de función estándar;
  • Líneas 20–25: g define this.prop2 y this.show en su interior, como lo haría el constructor de una clase;
  • línea 27: new (g as any)() **instancia **g como una clase.
npx tsx functions/func-04.ts

Resultado de la ejecución:

val1
val2
Nota: ES6 introdujo la palabra clave `class` (véase el capítulo “Clases”), que permite obtener este resultado directamente sin recurrir a este rodeo funcional.

3.6.5. Script [func-05]

Este script muestra el uso del [rest operator] (...), que reúne en un arreglo todos los argumentos restantes de una llamada:

'use strict';
// operador rest
function f(arg1: number, ...otherArgs: unknown[]): void {
  // 1.er argumento
  console.log("arg1=", arg1);
  // los demás argumentos
  let i = 0;
  otherArgs.forEach(element => {
    console.log("otherArguments[", i, "]=", element);
    i++;
  });
}

// llamada
f(1, "two", "three", { x: 2, y: 3 })
  • línea 3: function f(arg1: number, ...otherArgs: unknown[]): void — otherArgs reúne todos los argumentos pasados después de arg1, sea cual sea su número. El tipo unknown[] es apropiado aquí porque otherArgs mezcla intencionalmente tipos distintos (cadenas y objetos, en la llamada de la línea 15).
npx tsx functions/func-05.ts

Resultado de la ejecución:

1
2
3
4
arg1= 1
otherArguments[ 0 ]= two
otherArguments[ 1 ]= three
otherArguments[ 2 ]= { x: 2, y: 3 }

3.7. Errores y excepciones

TypeScript hereda de JavaScript el sistema de manejo de excepciones, que es bastante básico: la instrucción [throw] señala un error, y la estructura [try / catch / finally] lo captura. Los scripts de este capítulo se encuentran en la carpeta [exceptions] del proyecto.

Image

3.7.1. Script [excep-01]

Este script muestra la hora actual en el formato horas:minutos:segundos:milisegundos con la biblioteca [moment.js] (npm install moment) y luego demuestra cómo funciona try/catch/finally provocando un error según la paridad de los milisegundos actuales:

'use strict';

// paquete moment
import moment from 'moment';

// principio de try / catch / finally
for (let i = 0; i < 10; i++) {
  // fecha - hora del momento actual
  const now = Date.now();
  // formateo de la hora para obtener los milisegundos
  const time = moment(now).format("HH:mm:ss:SSS");
  // los milisegundos
  const milli = Number(time.substr(time.length - 3));
  // visualización
  console.log("--------------------iteration no. ", i, "at", time);
  try {
    // número aleatorio
    const nbr = milli % 2;
    if (nbr === 0) {
      // lanzar un mensaje de error
      throw "error";
    }
    // si llegamos aquí significa que no hubo error
    console.log("no error");
  } catch (error) {
    // si llegamos aquí, significa que hubo un error
    console.log("error1=", error);
  } finally {
    // se ejecuta en todos los casos, haya error o no
    console.log("finally")
  }
}
  • línea 4: import moment from 'moment' — importa una biblioteca de terceros, igual que sprintf-js en el capítulo “Cadenas de caracteres”;
  • en cada iteración del bucle, si el número actual de milisegundos es par, se lanza un error (línea 21) y lo captura el bloque catch; en caso contrario, se muestra el mensaje “no error”;
  • La cláusula [finally] se ejecuta siempre, haya ocurrido un error o no.

Este script depende de la hora exacta de ejecución: por lo tanto, el resultado que se muestra a continuación (obtenido de una ejecución real) será distinto en cada ejecución; solo está garantizado el principio (el bloque finally se ejecuta siempre):

npx tsx exceptions/excep-01.ts

Resultado de la ejecución:

--------------------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 demuestra que [throw] puede lanzar cualquier tipo de dato—cadena, arreglo, objeto o instancia de Error— y que la cláusula catch captura estos datos por completo:

'use strict';

// podemos "lanzar" prácticamente cualquier cosa para señalar un error
let i = 0;
console.log("--------------------attempt no. ", i);
// lanzar una cadena de caracteres
try {
  throw "error msg";
} catch (error) {
  // hubo un error
  console.log("error=[", error, "], type=", typeof (error));
}
// lanzar un objeto literal
i++;
console.log("--------------------attempt no. ", i);
try {
  throw [1, 2, 3]
} catch (error) {
  // hubo un error
  console.log("error=[", error, "], type=", typeof (error));
}
// lanzar un objeto
i++;
console.log("--------------------attempt no. ", i);
try {
  throw { name: "hercule", country: "ancient greece" }
} catch (error) {
  // hubo un error
  console.log("error=[", error, "], type=", typeof (error));
}
// lanzar un tipo Error
i++;
console.log("--------------------attempt no. ", i);
try {
  throw new Error("network connection error");
} catch (error) {
  // hubo un error
  console.log("error=[", error, "], type=", typeof (error));
}
// lanzar un tipo Error
i++;
console.log("--------------------attempt no. ", i);
try {
  throw new Error("network connection error");
} catch (error: any) {
  // hubo un error - el mensaje está en [error.message]
  // [any] porque TypeScript tipa por defecto las variables de catch como [unknown] (ver los otros
  // bloques try/catch de arriba, donde basta con mostrar [error] sin acceder a una propiedad)
  console.log("error.message=[", error.message, "], type(error)=", typeof (error));
}
  • [Error] es una clase integrada cuyo constructor acepta como primer parámetro un mensaje de error, que puede recuperarse en error.message;
  • TypeScript asigna a la variable de catch el tipo "unknown" por defecto (véase la nota de la línea 47): para acceder a una propiedad como .message se requiere entonces una verificación de tipo (instanceof, véase el siguiente script) o una anotación explícita en catch (error: any) como se muestra aquí en la línea 47;
  • Además de Error , hay otras clases que pueden usarse para señalar un error: EvalError, RangeError, ReferenceError, SyntaxError, TypeError, URIError.
npx tsx exceptions/excep-02.ts

Resultado de la ejecución:

--------------------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 muestra cómo distinguir, dentro de un bloque catch, el tipo específico del error capturado, mediante el operador [instanceof]:

'use strict';

// paquete moment
import moment from 'moment';

// diferenciación de la instancia de Error recibida en un [catch]
for (let i = 0; i < 10; i++) {
  // fecha - hora del momento actual
  const now = Date.now();
  // formateo de la hora para obtener los milisegundos
  const time = moment(now).format("HH:mm:ss:SSS");
  // los milisegundos
  const milli = Number(time.substr(time.length - 3));
  console.log("--------------------iteration no. ", i);
  try {
    // número aleatorio
    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) {
    // hubo un error
    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);
        }
      }
    }
  }
}

De nuevo, el resultado depende de la hora exacta de ejecución: cada ejecución produce una distribución distinta entre los tres tipos de error:

npx tsx exceptions/excep-03.ts

Resultado de la ejecución:

--------------------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]

[NEW since 2019] Este script incluye dos adiciones importantes introducidas con ECMAScript 2022: la opción [cause] de Error y las clases de error personalizadas.

'use strict';
// ========================================================================
// [NUEVO desde 2019] la propiedad [cause] de un error  (ECMAScript 2022)
// ========================================================================

// es común capturar un error técnico (de bajo nivel) y volver a
// lanzarlo como un error más explícito (de alto nivel), para que
// el código llamador comprenda mejor el contexto de negocio.
// ANTES de 2022, al hacer esto se perdía el rastro del error original.

function readConfiguration(): void {
  // simula un error técnico de bajo nivel (p. ej.: archivo no encontrado)
  throw new Error("ENOENT: file 'config.json' not found");
}

function startApplication(): void {
  try {
    readConfiguration();
  } catch (technicalError) {
    // el 2.º parámetro { cause } permite adjuntar el error original
    // al nuevo error, sin perder la información
    throw new Error("unable to start the application", { cause: technicalError });
  }
}

try {
  startApplication();
} catch (error: any) {
  console.log("error=", error.message);
  // error.cause da acceso al error original, muy útil para depurar
  console.log("cause=", error.cause?.message);
}

// ------------------------------------------------------------------------
// clases de error personalizadas (ya posibles desde ECMAScript 2015,
// pero muy a menudo usadas con [cause] desde 2022, de ahí que se revisen aquí)
// ------------------------------------------------------------------------
// podemos crear nuestros propios tipos de error extendiendo [Error], lo que permite luego
// distinguirlos con [instanceof], como con ReferenceError o RangeError
// (cf. exceptions/excep-03.js)
class ValidationError extends Error {

  fieldInError: string;

  constructor(message: string, fieldInError: string, options?: ErrorOptions) {
    // pasamos el mensaje y las [options] (incluida una posible cause) al [Error] padre
    super(message, options);
    // el nombre por defecto sería "Error"; lo personalizamos
    this.name = "ValidationError";
    // podemos agregar información de negocio propia de este tipo de error
    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;
}

// algunas pruebas con distintos valores
for (const value of [25, -5, "thirty", 200]) {
  try {
    validate(value);
    console.log(`value [${value}] : validation OK`);
  } catch (error) {
    // podemos distinguir nuestros errores de negocio de los demás errores gracias a instanceof
    if (error instanceof ValidationError) {
      console.log(`value [${value}] : validation error on [${error.fieldInError}] - ${error.message}`);
    } else {
      // un error inesperado, no previsto por nuestro código
      throw error;
    }
  }
}
  • líneas 17–22: Al capturar un error técnico de bajo nivel para relanzarlo en una forma más explícita, el segundo parámetro {cause} de new Error(...) permite conservar la traza del error original, que de otro modo se perdería (comportamiento anterior a 2022);
  • línea 31: error.cause?.message recupera el mensaje del error original, lo cual es muy útil para depurar;
  • líneas 41–53: Una clase de error personalizada (ValidationError extends Error) permite crear sus propios tipos de errores de negocio, que luego pueden distinguirse con instanceof (línea 72), igual que ReferenceError o RangeError en el script anterior.
npx tsx exceptions/excep-04.ts

Resultado de la ejecución:

1
2
3
4
5
6
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

Los módulos de ECMAScript permiten construir aplicaciones estructuradas en archivos independientes y reutilizables, cada uno de los cuales exporta lo que desea poner a disposición de los demás. Los scripts de este capítulo se encuentran en la carpeta [modules] del proyecto.

Image

3.8.1. Scripts [import-01, export-01]

El script [import-01] usa el módulo [export-01]:

1
2
3
4
5
6
7
// exportación por defecto de un objeto sin nombre
export default {
  data: 2,
  do() {
    console.log(this.data);
  }
};
  • [export default] exporta un objeto sin nombre; solo se permite una exportación predeterminada por módulo.
1
2
3
4
5
6
7
8
'use strict';
// importación de un objeto exportado por defecto
import export01 from './export-01.js';
// uso de este objeto
export01.do();
// una exportación por defecto se puede importar con cualquier nombre
import data from './export-01.js';
console.log(data.data);
  • Las líneas 3 y 7 importan la exportación predeterminada del módulo con dos nombres distintos (export01, y luego data); el nombre dado a la importación es arbitrario y no tiene que corresponder a nada del módulo de origen;
  • Una vez importado, el objeto puede usarse como si se hubiera definido localmente.
npx tsx modules/import-01.ts

Resultado de la ejecución:

2
2

3.8.2. Scripts [import-02, export-02]

Estos scripts muestran que exportar un objeto con nombre (almacenado previamente en una variable) funciona exactamente igual:

1
2
3
4
5
6
7
8
9
// exportación por defecto de un objeto con nombre
const data = {
  data: 2,
  do() {
    console.log(this.data);
  }
};
// exportación
export default data;
1
2
3
4
5
6
7
8
'use strict';
// importación de un objeto exportado por defecto
import module1 from './export-02.js';
// uso de este objeto
module1.do();
// una exportación por defecto se puede importar con cualquier nombre
import module2 from './export-02.js';
console.log(module2.data);
npx tsx modules/import-02.ts

Resultado de la ejecución:

2
2

3.8.3. Scripts [import-03, export-03]

Un módulo puede exportar varios elementos con la sintaxis export { element }:

// exportaciones múltiples
// exportación de un objeto
const data = {
  data: 2,
  do() {
    console.log(this.data);
  }
};
// exportación de una función
export { data };
function doSomething(): void {
  console.log("doSomething");
}
export { doSomething };
'use strict';
// importación de un módulo [export03]
import {data, doSomething} from './export-03.js';
// uso de las importaciones
data.do();
doSomething();
// otra sintaxis
import * as module from './export-03.js';
// uso de la importación
console.log(module.data);
module.doSomething();
  • Línea 3: Las importaciones con nombre usan los nombres exactos de los elementos exportados, entre llaves;
  • línea 8: import \* as module from '...' importa todos los elementos exportados, agrupados en un objeto con nombre (aquí, module).
npx tsx modules/import-03.ts

Resultado de la ejecución:

1
2
3
4
2
doSomething
{ data: 2, do: [Function: do] }
doSomething

3.8.4. Scripts [import-04, remote-config] — top-level await

[NEW since 2019] La versión 2022 de ECMAScript introdujo el top-level await: la posibilidad de usar await directamente en el nivel superior de un módulo, sin envolverlo en una función async. Antes había que crear una función “main” async y llamarla de inmediato (véase el siguiente capítulo, script async-06).

El módulo [remote-config] simula la carga de una configuración remota y usa await de nivel superior:

// módulo que simula la lectura de una configuración remota (p. ej.: llamada de red)
// usado por modules/import-04.js para ilustrar el top-level await

interface Configuration {
  applicationName: string;
  version: string;
}

// una función que simula una llamada asíncrona (p. ej.: fetch de un archivo de configuración)
function loadFromNetwork(): Promise<Configuration> {
  return new Promise(resolve => {
    setTimeout(() => {
      resolve({ applicationName: "ECMAScript course", version: "2026" });
    }, 300);
  });
}

// [NUEVO desde 2022] top-level await: podemos usar [await] directamente
// en el nivel superior de un módulo, sin envolverlo en una función async.
// el módulo COMPLETO (y todo módulo que lo importe) espera a que esta línea termine
// antes de continuar: es muy práctico para inicializar una configuración
// una sola vez, cuando se carga el módulo.
console.log("[remote-config] loading the configuration...");
const configuration: Configuration = await loadFromNetwork();
console.log("[remote-config] configuration loaded");

// exportamos el resultado, ya resuelto (y no una promesa a la que haya que volver a aplicar await)
export default configuration;

El script [import-04] importa este módulo:

'use strict';
// ========================================================================
// [NUEVO desde 2019] top-level await  (ECMAScript 2022)
// ========================================================================

// antes de ECMAScript 2022, era imposible usar [await] fuera de
// una función [async]: en el nivel superior de un script, había que crear
// una función "main" async y llamarla de inmediato (cf. async/async-06.js)

// nota sobre el orden de ejecución: con los módulos ES, los [import] siempre se
// evalúan ANTES del código del módulo importador, aunque estén escritos en la 1.ª línea.
// por eso los logs de [remote-config.js] se muestran antes que este,
// aunque la línea siguiente esté textualmente colocada antes del import en este archivo.
console.log("[import-04] before importing the remote-config module");

// gracias al top-level await usado EN remote-config.js, el import de abajo
// solo se completa cuando la configuración ha terminado de cargarse: no hace falta
// llamar a .then() ni crear una función async aquí
import configuration from './remote-config.js';

console.log("[import-04] after the import: the configuration is already available");
console.log("configuration =", configuration);

// también podemos usar [await] directamente aquí, en este módulo, en el nivel superior
console.log("[import-04] waiting 200ms with top-level await...");
await new Promise(resolve => setTimeout(resolve, 200));
console.log("[import-04] finished");
  • Línea 19: Gracias al await de nivel superior usado **en **remote-config.ts, la importación de la línea 19 se completa solo después de que la configuración haya terminado de cargarse; aquí no se necesita .then() ni una función async ;
  • Los módulos ES se evalúan siempre antes que el código del módulo que los importa, incluso si la instrucción import no está en la primera línea del archivo: por eso los mensajes de remote-config.ts se muestran antes que los de import-04.ts, aunque estos últimos estén literalmente colocados antes del import en el archivo;
  • línea 26: También se puede usar await directamente dentro de import-04.ts , en su propio nivel superior.
npx tsx modules/import-04.ts

Resultado de la ejecución:

1
2
3
4
5
6
7
[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. Programación orientada a eventos y funciones asíncronas

Una función asíncrona es una función cuya ejecución se inicia pero cuyo resultado no se espera de inmediato. Cuando la ejecución termina, la función asíncrona señala su resultado, mediante un evento o mediante una **[Promise]**, como veremos más adelante.

Este modo de funcionamiento es muy adecuado para la ejecución en un navegador, donde la aplicación responde constantemente a eventos (clics, pulsaciones de teclas, respuestas de red, etc.). Los scripts de este capítulo los ejecuta [node.js], que también utiliza un bucle de eventos:

  • la ejecución del código principal del script es el primer evento procesado;
  • si este código ha iniciado tareas asíncronas, la ejecución del script continúa hasta que terminen; al finalizar emiten un evento, que se coloca en la cola del bucle de eventos;
  • el script principal debe suscribirse a estos eventos para recuperar sus resultados;
  • el script no termina hasta que todos los eventos que ha emitido se hayan procesado.

Los scripts de este capítulo se encuentran en la carpeta [async] del proyecto.

Image

3.9.1. Script [async-01]

Este script muestra el comportamiento de un script que contiene una acción asíncrona, usando la función nativa [setTimeout]:

'use strict';

// importaciones
import moment from 'moment';
import { sprintf } from 'sprintf-js';

// inicio
const scriptStart = moment(Date.now());
console.log("[start of the script],", time());

// setTimeout arma un temporizador de 1000 ms (2.º parámetro) y devuelve de inmediato el número de este temporizador
// cuando el temporizador agota los 1000 ms emite un evento que se coloca en la cola del entorno de ejecución
// cuando el entorno de ejecución procesa el evento, se ejecuta la función (1.er parámetro)
setTimeout(function () {
  // este código se ejecutará cuando el temporizador haya llegado al valor 0
  console.log("[end of the asynchronous action setTimeout],", time(scriptStart));
}, 1000)

// se mostrará antes que el mensaje de la función interna del temporizador
console.log("[end of the main code of the script],", time(scriptStart));

// utilidad que muestra la hora y la duración
function time(start?: moment.Moment): string {
  // hora del momento actual
  const now = moment(Date.now());
  // formateo de la hora
  let result = "time=" + now.format("HH:mm:ss:SSS");
  // ¿se debe calcular una duración?
  if (start) {
    const duration = now.valueOf() - start.valueOf();
    const milliseconds = duration % 1000;
    const seconds = Math.floor(duration / 1000);
    // formateo de hora + duración
    result = result + sprintf(", duration= %s second(s) and %s milliseconds", seconds, milliseconds);
  }
  // resultado
  return result;
}
  • Líneas 14–17: [setTimeout] recibe dos parámetros: una función por ejecutar y un retardo en milisegundos. Se ejecuta al instante: inicia un temporizador y devuelve el control de inmediato, sin esperar a que transcurra el retardo;
  • línea 20: este mensaje aparece, por lo tanto, antes que el de la línea 16, aunque esté escrito más adelante en el código;
  • línea 23: function time(start?: moment.Moment): string — el parámetro start es opcional (?), de tipo moment.Moment; si se proporciona, la función calcula y agrega el tiempo transcurrido.
npx tsx async/async-01.ts

Resultado de la ejecución:

1
2
3
[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 la acción asíncrona setTimeout termina aproximadamente 1 segundo después de que finaliza el código principal, que es exactamente el retardo programado. Sin embargo, el script en conjunto no termina hasta que esta tarea asíncrona ha finalizado.

Nota: Usaremos setTimeout para simular tareas asíncronas a lo largo de este capítulo. Una tarea asíncrona real (solicitud de red, lectura de un archivo, etc.) se comporta de la misma manera: cede el control de inmediato y luego informa su resultado más tarde, normalmente mediante dos posibles eventos, uno para el éxito y otro para el fallo.

3.9.2. Script [async-02]

Este script muestra cómo una función asíncrona puede comunicar su resultado emitiendo eventos, con la clase nativa EventEmitter (módulo node:events):

'use strict';

// las funciones asíncronas pueden devolver un resultado emitiendo un evento
// el código principal puede recuperar estos resultados suscribiéndose a los eventos emitidos

// importaciones
import moment from 'moment';
import { sprintf } from 'sprintf-js';
import EventEmitter from 'events';

// inicio
const scriptStart = moment(Date.now());
console.log("[start of the script],", time());
// un emisor de eventos
const eventEmitter = new EventEmitter();

// setTimeout arma un temporizador de 1000 ms (2.º parámetro) y devuelve de inmediato el número de este temporizador
// cuando el temporizador agota los 1000 ms emite un evento que se coloca en la cola del entorno de ejecución
// cuando el entorno de ejecución procesa el evento, se ejecuta la función (1.er parámetro)
setTimeout(function () {
  // este código se ejecutará cuando el temporizador haya llegado al valor 0
  console.log("[setTimeout, end of the 1 s timer],", time(scriptStart));
  // emitimos un evento para decir que hay un resultado disponible
  eventEmitter.emit("timer1Success", { success: 4 });
  // emitimos otro evento para decir que hay otro resultado disponible
  eventEmitter.emit("timer1Failure", { failure: 6 });
}, 1000)

// nos suscribimos al 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)));
});

// nos suscribimos al 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)));
});

// se mostrará antes que los mensajes de los evts emitidos por la función asociada a [timer1]
console.log("[end of the main code of the script],", time(scriptStart));

// utilidad que muestra la hora y la duración
function time(start?: moment.Moment): string {
  // hora del momento actual
  const now = moment(Date.now());
  // formateo de la hora
  let result = "time=" + now.format("HH:mm:ss:SSS");
  // ¿se debe calcular una duración?
  if (start) {
    const duration = now.valueOf() - start.valueOf();
    const milliseconds = duration % 1000;
    const seconds = Math.floor(duration / 1000);
    // formateo de hora + duración
    result = result + sprintf(", duration= %s second(s) and %s milliseconds", seconds, milliseconds);
  }
  // resultado
  return result;
}
  • línea 9: import EventEmitter from 'events' — importa la clase que permite emitir y escuchar eventos;
  • línea 15: const eventEmitter = new EventEmitter() — se instancia un emisor de eventos con new;
  • líneas 24 y 26: la función encapsulada en setTimeout emite dos eventos, timer1Success y timer1Failure, cada uno con sus propios datos asociados (aquí solo con fines de demostración; normalmente, una misma tarea emitiría solo uno u otro);
  • líneas 29–37: el código principal se suscribe a estos dos eventos con eventEmitter.on(eventName, callback); el callback no se ejecutará hasta que el evento se emita realmente, no en el momento de la suscripción;
  • línea 40: el código principal termina aquí, pero el script global no termina hasta que la tarea asíncrona (y los callbacks suscritos) hayan terminado de ejecutarse.
npx tsx async/async-02.ts

Resultado de la ejecución:

1
2
3
4
5
[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]

El bucle de eventos de node.js ejecuta un solo evento a la vez: el siguiente evento se procesa solo después de que el anterior haya terminado. Por lo tanto, el código síncrono que acapara el procesador durante mucho tiempo retrasa el procesamiento de todos los eventos pendientes, incluidos los que ya se han emitido. Este script (idéntico a async-02, con un bucle intensivo agregado) lo demuestra:

'use strict';

// las funciones asíncronas pueden devolver un resultado emitiendo un evento
// el código principal puede recuperar estos resultados suscribiéndose a los eventos emitidos

// importaciones
import moment from 'moment';
import { sprintf } from 'sprintf-js';
import EventEmitter from 'events';

// inicio
const scriptStart = moment(Date.now());
console.log("[start of the script],", time());
// un emisor de eventos
const eventEmitter = new EventEmitter();

// setTimeout arma un temporizador de 1000 ms (2.º parámetro) y devuelve de inmediato el número de este temporizador
// cuando el temporizador agota los 1000 ms emite un evento que se coloca en la cola del entorno de ejecución
// cuando el entorno de ejecución procesa el evento, se ejecuta la función (1.er parámetro)
setTimeout(function () {
  // este código se ejecutará cuando el temporizador haya llegado al valor 0
  console.log("[setTimeout, end of the 1 s timer],", time(scriptStart));
  // emitimos un evento para decir que hay un resultado disponible
  eventEmitter.emit("timer1Success", { success: 4 });
  // emitimos otro evento para decir que hay otro resultado disponible
  eventEmitter.emit("timer1Failure", { failure: 6 });
}, 1000)

// nos suscribimos al 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)));
});

// nos suscribimos al 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 algo intensivo que impidió que el código principal terminara antes del final de [timer1]
for (let i = 0; i < 1000000; i++) {
  for (let j = 0; j < 10000; j++) {
    i + i ^ 2 + i ^ 3;
  }
}

// se mostrará antes que los mensajes de los evts emitidos por la función asociada a [timer1]
console.log("[end of the main code of the script],", time(scriptStart));

// utilidad que muestra la hora y la duración
function time(start?: moment.Moment): string {
  // hora del momento actual
  const now = moment(Date.now());
  // formateo de la hora
  let result = "time=" + now.format("HH:mm:ss:SSS");
  // ¿se debe calcular una duración?
  if (start) {
    const duration = now.valueOf() - start.valueOf();
    const milliseconds = duration % 1000;
    const seconds = Math.floor(duration / 1000);
    // formateo de hora + duración
    result = result + sprintf(", duration= %s second(s) and %s milliseconds", seconds, milliseconds);
  }
  // resultado
  return result;
}
  • líneas 40–44: un doble bucle puramente síncrono, sin relación con la tarea asíncrona, pero que ocupa el procesador durante varios segundos;
  • el temporizador de 1 segundo terminó su cuenta regresiva mucho antes del final de este bucle, pero el evento que emitió debe esperar a que el código síncrono devuelva el control al bucle de eventos antes de poder procesarse por fin.
npx tsx async/async-03.ts

Resultado de la ejecución:

1
2
3
4
5
[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

El código principal tardó aproximadamente 5,7 segundos en ejecutarse (la duración varía según la máquina), aunque el temporizador había terminado hacía mucho su cuenta regresiva de un segundo: el evento asociado tuvo que esperar a que terminara el bucle síncrono. Es importante tener en cuenta que el código síncrono de larga duración debería, siempre que sea posible, dividirse en tareas asíncronas más cortas.

3.9.4. El mecanismo de las promesas

El tipo [Promise] es una clase que evita gestionar eventos de forma explícita: esto se hace de manera implícita, pero entender los eventos subyacentes ayuda a comprender mejor su funcionamiento. Su constructor recibe como parámetro una función asíncrona, a la que le pasa dos funciones, llamadas tradicionalmente [resolve] y [reject]:

const promise = new Promise(function (resolve, reject) {
  // se inicia una tarea asíncrona
  // ...
  // si tiene éxito: se llama a resolve(result) donde [result] es el resultado de la tarea
  // si falla: se llama a reject(error) donde [error] encapsula el error encontrado
});

Un objeto Promise puede encontrarse en uno de cuatro estados:

  • [pending]: la tarea asíncrona aún no ha terminado;
  • [fulfilled]: terminó con éxito;
  • [rejected]: falló;
  • [settled]: terminó (sin importar si tuvo éxito o falló).

Uno se suscribe a los resultados de una Promise con la sintaxis promise.then(f1).catch(f2).finally(f3): f1 se ejecuta en caso de éxito (recibe el resultado pasado por resolve), f2 se ejecuta en caso de fallo (recibe el error devuelto por reject) y f3 se ejecuta en todos los casos, sin ningún parámetro.

3.9.5. Script [async-04]

Este script crea dos Promises independientes, cada una de las cuales encapsula un setTimeout, y se suscribe a sus resultados:

'use strict';

// es posible obtener los resultados (éxito, fallo) de una función asíncrona
// sin usar explícitamente eventos gracias a la clase [Promise]
// esta clase usa eventos de forma implícita pero no son visibles en el código

// importaciones
import moment from 'moment';
import { sprintf } from 'sprintf-js';

// inicio
const scriptStart = moment(Date.now());
console.log("[start of the script],", time(scriptStart));

// definición de una tarea asíncrona mediante una [Promise]
// la tarea asíncrona es el parámetro del constructor 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 asíncrono
  setTimeout(function () {
    // este código se ejecuta tras un retraso de 1 segundo (2.º parámetro)
    console.log("[end of the asynchronous function of promise1],", time(promise1Start));
    // la tarea asíncrona devuelve un resultado con la función [resolve]
    // la promesa tiene entonces éxito
    resolve('[success]');
  }, 1000)
});

// podemos conocer el resultado de la promesa [promise1]
// cuando se ha resuelto (resolve) o rechazado (reject)
// la siguiente instrucción es una suscripción al evt [resolved] mediante el método [then]
// y al evt [rejected] mediante el método [catch]
// el método [finally] se ejecuta tanto después de un then como de un catch
promise1.then(result => {
  // caso en que la promesa tiene éxito  [evt resolved]
  console.log(sprintf("[promise1.then], %s, result=%s", time(promise1Start), result));
}).catch(result => {
  // caso de error  [evt rejected]
  console.log(sprintf("[promise1.catch], %s, result=%s", time(promise1Start), result));
}).finally(() => {
  // se ejecuta en todos los casos
  console.log("[promise1.finally]", time(promise1Start));
});

// definición de una tarea asíncrona mediante una [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));
  // tarea asíncrona
  setTimeout(function () {
    console.log("[end of the asynchronous function of promise2],", time(promise2Start));
    // la tarea asíncrona devuelve un resultado con la función [reject]
    // la promesa ha fallado entonces
    reject('[failure]');
  }, 2000)
});

// podemos conocer el resultado de la promesa [promise2]
// cuando se ha resuelto (resolve) o rechazado (reject)
promise2.then(result => {
  // caso en que la promesa tiene éxito [evt resolved]
  console.log(sprintf("[promise2.then], %s, result=%s", time(promise2Start), result));
}).catch(result => {
  // caso de error [evt rejected]
  console.log(sprintf("[promise2.catch], %s, result=%s", time(promise2Start), result));
}).finally(() => {
  // se ejecuta en todos los casos
  console.log(sprintf("[promise2.finally], %s", time(promise2Start)));
});

// se mostrará antes que los mensajes de las funciones asíncronas y los de los evts asociados
console.log("[end of the main code of the script],", time(scriptStart));

// utilidad
function time(start?: moment.Moment): string {
  // hora del momento actual
  const now = moment(Date.now());
  // formateo de la 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);
    // formateo de la duración
    result = result + sprintf(", duration= %s second(s) and %s milliseconds", seconds, milliseconds);
  }
  // resultado
  return result;
}
  • línea 18: new Promise<string>(function (resolve) {...}) — TypeScript permite especificar, mediante el parámetro genérico <string>, el tipo de valor que resolve devolverá; sin él, el tipo se inferiría como unknown;
  • promise1 se resuelve con éxito después de 1 segundo (resolve('[success]')); promise2 falla después de 2 segundos (reject('[failure]'));
  • el código principal (línea 75) termina mucho antes de que ambas promesas tengan un resultado; sin embargo, el script global continúa hasta que ambas se han establecido.
npx tsx async/async-04.ts

Resultado de la ejecución:

[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]

Lo más habitual es definir una función asíncrona que devuelve una Promise, en lugar de crear directamente el objeto Promise, lo cual es útil cuando la función necesita parámetros. Este script define dos funciones asíncronas y espera a que ambas terminen con [Promise.all]:

'use strict';

// podemos definir funciones asíncronas que devuelven un tipo [Promise]
// pueden entonces marcarse con la palabra clave [async]
// aquí de nuevo
// importaciones
import moment from 'moment';
import { sprintf } from 'sprintf-js';

// inicio
const scriptStart = moment(Date.now());
console.log("[start of the script],", time());

// forma del resultado devuelto por async01 y async02
interface AsyncResult {
  prop1: number[];
  prop2: string;
  prop3: number;
}

// una función asíncrona puede devolver una [Promise]
// y tener además el atributo [async]
async function async01(p1: number): Promise<AsyncResult> {
  return new Promise<AsyncResult>(resolve => {
    console.log("[start of the asynchronous task async01]");
    // la tarea asíncrona
    const async01Start = moment(Date.now());
    setTimeout(function () {
      // este código se ejecuta tras un retraso de 1 segundo (2.º parámetro)
      console.log("[end of the asynchronous task async01],", time(async01Start));
      // la tarea asíncrona puede devolver un resultado complejo
      resolve({
        prop1: [10, 20, 30],
        prop2: "abcd",
        prop3: p1,
      });
    }, 1000)
  });
}

// una función puede devolver una [Promise]
// y puede tener entonces el atributo [async]
async function async02(p1: number, p2: number): Promise<AsyncResult> {
  return new Promise<AsyncResult>(resolve => {
    console.log("[start of the asynchronous task async02]");
    // tarea asíncrona
    const async02Start = moment(Date.now());
    setTimeout(function () {
      // el siguiente código se ejecuta tras un retraso de 2 segundos (2.º parámetro)
      console.log("[end of the asynchronous task async02],", time(async02Start));
      // la tarea asíncrona puede devolver un resultado complejo
      resolve({
        prop1: [11, 21, 31],
        prop2: "xyzt",
        prop3: p1 + p2
      });
    }, 2000)
  })
}

// lanzamos las dos funciones asíncronas en paralelo
// y esperamos a que ambas terminen
// el then solo se ejecutará si ambas funciones han emitido el evt [resolved]
// el catch se ejecutará en cuanto una de las dos funciones emita el evt [rejected]
Promise.all([async01(10), async02(10, 20)])
  // el resultado es un arreglo [result1, result2] donde [result1] es el resultado emitido por un [resolve] de [async01]
  // y [result2] el resultado emitido por un [resolve] de [async02]
  .then(result => {
    console.log(sprintf("[promise-all success], %s, result=%j", time(scriptStart), result));
  })
  // error es el resultado emitido por el primer [reject] de una de las dos funciones asíncronas
  .catch(error => {
    console.log(sprintf("[promise-all error], %s, error=%j", time(scriptStart), error));
  })
  // finally se ejecuta después del then o del catch
  .finally(() => {
    console.log(sprintf("[promise-all finally], %s", time(scriptStart)));
  });

// se mostrará antes que los mensajes de las funciones asíncronas y de los evts asociados
console.log("[end of the main code of the script],", time(scriptStart));

// utilidad
function time(start?: moment.Moment): string {
  // hora del momento actual
  const now = moment(Date.now());
  // formateo de la 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);
    // formateo de la duración
    result = result + sprintf(", duration= %s second(s) and %s milliseconds", seconds, milliseconds);
  }
  // resultado
  return result;
}
  • líneas 23 y 43: las funciones asíncronas se tipan como Promise<AsyncResult> gracias a la interfaz AsyncResult definida más arriba;
  • línea 65: [Promise.all([...])] espera a que todas las promesas del arreglo se resuelvan antes de ejecutar su then; en cuanto una falla, su catch se ejecuta de inmediato, sin esperar a las demás;
  • las dos tareas se ejecutan en paralelo (sus respectivos tiempos de espera se superponen): la duración total (~2 s) corresponde a la más larga de las dos, no a su suma (~3 s).
npx tsx async/async-05.ts

Resultado de la ejecución:

1
2
3
4
5
6
7
8
[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

Las palabras clave [async]/[await] permiten escribir código asíncrono que parece código síncrono: el manejo de eventos subyacente queda completamente oculto, lo que hace el código mucho más fácil de leer. Este script define tres funciones asíncronas (la tercera falla intencionalmente) y las ejecuta primero de forma secuencial, y luego en paralelo:

'use strict';

// ejecución paralela o secuencial de varias tareas asíncronas
// con las palabras clave async / await

// importaciones
import moment from 'moment';
import { sprintf } from 'sprintf-js';

// inicio
const scriptStart = moment(Date.now());
console.log("[start of the main code of the script],", time());

// forma del resultado devuelto por async01/async02/async03
interface AsyncResult {
  prop1: number[];
  prop2: string;
}

// una función asíncrona que devuelve una [Promise]
async function async01(async01Start: moment.Moment): Promise<AsyncResult> {
  return new Promise(function (resolve) {
    console.log("[start of the asynchronous function async01],", time());
    // función asíncrona
    setTimeout(function () {
      console.log("[end of the asynchronous function async01],", time(async01Start));
      // la acción asíncrona puede devolver un resultado complejo
      // aquí éxito
      resolve({
        prop1: [11, 21, 31],
        prop2: "abcd"
      });
    }, 1000)
  });
}

// una función asíncrona que devuelve una [Promise]
async function async02(async02Start: moment.Moment): Promise<AsyncResult> {
  console.log("[start of the asynchronous function async02],", time());
  return new Promise(function (resolve) {
    // función asíncrona
    setTimeout(function () {
      console.log("[end of the asynchronous function async02],", time(async02Start));
      // la acción asíncrona puede devolver un resultado complejo
      // aquí éxito
      resolve({
        prop1: [12, 22, 32],
        prop2: "xyzt"
      });
    }, 2000)
  })
}

// una función asíncrona que devuelve una [Promise]
async function async03(async03Start: moment.Moment): Promise<AsyncResult> {
  console.log("[start of the asynchronous function async03],", time());
  return new Promise((resolve, reject) => {
    // función asíncrona
    setTimeout(function () {
      console.log("[end of the asynchronous function async03],", time(async03Start));
      // la acción asíncrona puede devolver un resultado complejo
      // aquí fallo
      reject({
        prop1: [13, 23, 33],
        prop2: "failure"
      });
    }, 3000)
  })
}

// función asíncrona - uso de async / await
async function main(): Promise<void> {
  const sequentialStart = moment(Date.now());
  // ejecución secuencial de las tareas asíncronas
  console.log("------------ sequential execution of the asynchronous tasks started ------------------------")
  try {
    // ejecución con espera de [async01]
    const async01Start = moment(Date.now());
    const result1 = await async01(async01Start);
    console.log("[async01 result]=", result1);
    // ejecución con espera de [async02]
    const async02Start = moment(Date.now());
    console.log("start async02-------------", time());
    const result2 = await async02(async02Start);
    console.log("[async02 result]=", result2);
    // ejecución con 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) {
    // una de las acciones asíncronas falló
    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());
  // ejecución paralela de las tareas así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) {
    // una de las acciones asíncronas falló
    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));
}
// ejecución de la función principal asíncrona
main();

// se mostrará antes que los distintos mensajes de las funciones asíncronas y de sus evts
console.log("[end of the main code of the script],", time(scriptStart));

// utilidad
function time(start?: moment.Moment): string {
  // hora del momento actual
  const now = moment(Date.now());
  // formateo de la 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);
    // formateo de la duración
    result = result + sprintf(", duration= %s second(s) and %s milliseconds", seconds, milliseconds);
  }
  // resultado
  return result;
}
  • línea 72: async function main(): Promise<void> — una función marcada con async siempre devuelve una Promise, aunque su cuerpo no lo indique explícitamente;
  • línea 79: await async01(async01Start) suspende la ejecución de main hasta que la promesa se resuelve, sin bloquear el resto del programa (la palabra clave await solo puede usarse dentro de una función async o en el nivel superior de un módulo; véase el capítulo “Módulos”, script import-04);
  • líneas 76–90: ejecución secuencial; cada await espera a que termine la tarea anterior antes de iniciar la siguiente; la duración total es la suma de los tres tiempos de espera (~6 s);
  • líneas 102–111: ejecución en paralelo, con await Promise.all([...]); la duración total es la de la tarea más larga (~3 s);
  • Un bloque try/catch estándar basta para manejar el fallo de una promesa esperada; ya no hay necesidad de encadenar llamadas a .catch() como en los scripts anteriores.
npx tsx async/async-06.ts

Resultado de la ejecución:

[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

La diferencia en el tiempo total de ejecución es claramente evidente: ~6 s en modo secuencial frente a ~3 s en modo paralelo para las mismas tres tareas (1 s + 2 s + 3 s).

3.9.8. [async-07] script: extensiones de Promise

[NUEVO desde 2019] Este script presenta cuatro extensiones introducidas entre 2020 y 2024, que hoy se usan ampliamente en el TypeScript moderno:

'use strict';
// ========================================================================
// [NUEVO desde 2019] adiciones a la clase Promise
// ========================================================================

// pequeña función utilitaria: devuelve una promesa que tiene éxito o falla tras [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 muestra Promise.all(): si UNA de las promesas falla, se activa el catch
// y perdemos el resultado de las demás promesas que, por su parte, habían tenido éxito
// Promise.allSettled() espera SIEMPRE a que todas las promesas hayan terminado
// (con éxito o con fallo) y devuelve el detalle de cada una, sin rechazar nunca
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 tiene la forma { status: "fulfilled", value: ... } o { 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)
// ------------------------------------------------------------------------
// devuelve el resultado de la PRIMERA promesa que tiene éxito (las demás se ignoran)
// rechaza solo si TODAS las promesas fallan (con un AggregateError que agrupa los errores)
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 contiene la lista de todos los errores individuales
    console.log("all the mirrors failed :", globalError.errors);
  }
}

// ------------------------------------------------------------------------
// 3) Promise.withResolvers()  (ECMAScript 2024)
// ------------------------------------------------------------------------
// antes, para "sacar" las funciones resolve/reject del constructor de Promise
// (p. ej. para llamarlas mucho más tarde, en otra parte del código), se necesitaba
// una variable intermedia algo artificial:
//   let externalResolve;
//   const promise = new Promise(resolve => { externalResolve = resolve; });
// Promise.withResolvers() hace esto directamente, en una sola expresión
function demoWithResolvers(): Promise<string> {
  console.log("--- Promise.withResolvers ---");
  const { promise, resolve } = Promise.withResolvers<string>();

  // podemos resolver la promesa desde cualquier lugar, por ejemplo en otro callback
  setTimeout(() => {
    console.log("[external callback] we trigger the resolution of the promise");
    resolve("value passed from an external callback");
  }, 200);

  return promise;
}

// ------------------------------------------------------------------------
// 4) cancelación de una operación asíncrona con AbortController
// ------------------------------------------------------------------------
// AbortController permite cancelar una operación asíncrona en curso (fetch, temporizadores, ...)
// es el mecanismo estándar que usa [fetch] para los tiempos de espera (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);
    // si se activa la señal de cancelación, detenemos todo y rechazamos
    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 la cancelación a los 100 ms, antes del final normal de la tarea (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);
  }
}

// ejecución sucesiva de las demostraciones
async function main(): Promise<void> {
  await demoAllSettled();
  await demoAny();
  console.log("--- Promise.withResolvers, result ---", await demoWithResolvers());
  await demoAbortController();
}

main();
  • [Promise.allSettled] (ES2020): a diferencia de Promise.all (async-05 script), siempre espera a que todas las promesas terminen, ya sea con éxito o con error, y devuelve el detalle de cada una; es útil cuando no se quiere perder nunca los resultados de las tareas que tuvieron éxito, aunque otra haya fallado;
  • [Promise.any] (ES2021): devuelve el resultado de la primera promesa que tiene éxito e ignora las demás; solo es rechazada si todas fallan;
  • [Promise.withResolvers] (ES2024): extrae resolve y reject del constructor de Promise en una sola expresión, lo que resulta útil para resolver una promesa más tarde desde otra parte del código;
  • [AbortController]: permite cancelar una operación asíncrona pendiente; es el mecanismo estándar que usa fetch para los tiempos de espera (consulte el capítulo “Las funciones HTTP”).
npx tsx async/async-07.ts

Resultado de la ejecución:

--- 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. Las clases

Aquí presentamos las clases de ECMAScript, tipadas en TypeScript. Antes de presentarlas, recordemos (script class-00, ya tratado en el capítulo “Las funciones” con el nombre func-04) que las funciones ya pueden comportarse como clases; es este mecanismo histórico el que la palabra clave [class] simplifica.

Los scripts de este capítulo se encuentran en la carpeta [classes] del proyecto.

Image

3.10.1. script [class-00]

Recordatorio del mecanismo histórico (funciones usadas como clases):

'use strict';
// una función se puede usar como un objeto

// una cáscara vacía
// [any]: el tipo de [this] es deliberadamente laxo aquí, porque asignamos
// propiedades a la propia función DESPUÉS de su definición (ver más abajo) -
// un patrón que TypeScript no puede inferir por sí solo
function f(this: any): void {

}
// a la cual asignamos propiedades desde el exterior
(f as any).prop1 = "val1";
(f as any).show = function (this: any) {
  console.log(this.prop1);
};
// uso de f
(f as any).show();

// una función g que funciona como una clase
function g(this: any): void {
  this.prop2 = "val2";
  this.show = function (this: any) {
    console.log(this.prop2);
  };
}
// instanciación de la función con [new]
new (g as any)().show();
npx tsx classes/class-00.ts

Resultado de la ejecución:

val1
val2
Nota: ES6 introdujo la palabra clave `class`, que permite obtener el mismo resultado de manera mucho más legible y confiable, sin recurrir a esta solución funcional, como lo demuestran los scripts siguientes.

3.10.2. script [class-01]

Este script define una clase llamada [Person], con un constructor, getters/setters y el método toString:

// clase
class Person {

  private _lastName!: string;
  private _firstName!: string;
  private _age!: number;

  // constructor
  constructor(lastName: string, firstName: string, age: number) {
    this.lastName = lastName;
    this.firstName = firstName;
    this.age = age;
  }

  // getters y 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 en JSON
  toString(): string {
    return JSON.stringify(this);
  }
}

// uso de la clase
function main(): void {
  const person = new Person("Poirot", "Hercule", 66);
  console.log("person=", person.toString(), typeof (person), person instanceof (Person));
}

// llamada a main
main();
  • línea 2: [class] introduce la clase;
  • línea 9: [constructor] es su constructor; solo puede haber uno por clase;
  • líneas 4–6: los campos _lastName, _firstName y _age se declaran con el modificador [private], lo que los hace accesibles solo desde dentro de la clase, a diferencia de una simple convención de nomenclatura. El ! (*aserción de asignación definitiva*) le indica a TypeScript que estos campos efectivamente serán asignados antes de cualquier lectura, aunque esto no sea visible directamente en su declaración (el constructor, mediante los setters, se encarga de ello);
  • líneas 16–35: getters y setters, con una sintaxis idéntica a la vista para los objetos literales (capítulo “Objetos literales”, script obj-03), pero integrados en la clase;
  • línea 46: person instanceof (Person): es posible determinar el tipo exacto de una instancia de clase, a diferencia de lo que ocurre con los objetos literales.
npx tsx classes/class-01.ts

Resultado de la ejecución:

person= {"_lastName":"Poirot","_firstName":"Hercule","_age":66} object true

3.10.3. script [class-02]: herencia

Este script demuestra la herencia mediante la palabra clave [extends]. Primero se aísla la clase Person en su propio archivo, Person.ts:

// clase
class Person {

  // propiedades privadas (a las que se accede mediante los getters/setters de abajo)
  // [!]: afirmamos a TypeScript que se asignarán antes de ser leídas
  // (aquí, mediante el constructor que llama a los setters)
  private _lastName!: string;
  private _firstName!: string;
  private _age!: number;

  // constructor
  constructor(lastName: string, firstName: string, age: number) {
    this.lastName = lastName;
    this.firstName = firstName;
    this.age = age;
  }

  // getters y 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 en JSON
  toString(): string {
    return JSON.stringify(this);
  }
}
// exportación de la clase
export default Person;

El script [class-02] crea una clase [Teacher] derivada de Person:

// importaciones
// [actualización 2026] con el ESM nativo de node, la extensión .js es obligatoria
// en las rutas relativas (era opcional con el cargador [esm] usado en 2019)
import Person from './Person.js';

// clase
class Teacher extends Person {

  private _subject!: string;

  // constructor
  constructor(lastName: string, firstName: string, age: number, subject: string) {
    super(lastName, firstName, age);
    this.subject = subject;
  }

  // getters y setters
  get subject(): string {
    return this._subject;
  }
  set subject(value: string) {
    this._subject = value;
  }

}

// uso de la clase
function main(): void {
  const teacher = new Teacher("Poirot", "Hercule", 66, "detective");
  console.log("teacher=", teacher.toString(), typeof (teacher), teacher instanceof Teacher);
}

// llamada a main
main();
  • línea 5: import Person from './Person.js' : la clase se importa desde su módulo. La extensión .js (y no .ts) es obligatoria con la resolución de módulos moderna de Node.js, aunque el archivo fuente sea un archivo .ts (consulte el capítulo “Instalación”);
  • línea 8: class Teacher extends Person : Teacher hereda todos los miembros de Person y agrega una propiedad _subject con su getter/setter;
  • línea 14: super(lastName, firstName, age) llama al constructor de la clase padre, que inicializa _lastName, _firstName y _age;
  • línea 31: teacher instanceof Teacher: TypeScript/JavaScript conoce el tipo exacto de la instancia, incluso después de la herencia.
npx tsx classes/class-02.ts

Resultado de la ejecución:

teacher= {"_lastName":"Poirot","_firstName":"Hercule","_age":66,"_subject":"detective"} object true

3.10.4. script [class-03]: sobrescritura de métodos

Este script demuestra que una clase hija puede sobrescribir un método de su clase padre, en este caso toString:

// importaciones
// [actualización 2026] con el ESM nativo de node, la extensión .js es obligatoria
// en las rutas relativas (era opcional con el cargador [esm] usado en 2019)
import Person from './Person.js';

// clase
class Teacher extends Person {

  private _subject!: string;

  // constructor
  constructor(lastName: string, firstName: string, age: number, subject: string) {
    super(lastName, firstName, age);
    this.subject = subject;
  }

  // getters y setters
  get subject(): string {
    return this._subject;
  }
  set subject(value: string) {
    this._subject = value;
  }

  // redefinición de toString
  toString(): string {
    return "[Teacher]" + JSON.stringify(this);
  }
}

// uso de la clase
function main(): void {
  const teacher = new Teacher("Poirot", "Hercule", 66, "detective");
  console.log("teacher=", teacher.toString(), typeof (teacher), teacher instanceof Teacher);
}

// llamada a main
main();
npx tsx classes/class-03.ts

Resultado de la ejecución:

teacher= [Teacher]{"_lastName":"Poirot","_firstName":"Hercule","_age":66,"_subject":"detective"} object true

3.10.5. script [class-04]: polimorfismo

Este script demuestra el polimorfismo en acción: cuando una función espera un parámetro de tipo Person, podemos pasarle un tipo derivado como Teacher, ya que posee todos los atributos de Person. Primero aislamos Teacher en su propio módulo, Teacher.ts:

// importaciones
// [actualización 2026] con el ESM nativo de node, la extensión .js es obligatoria
// en las rutas relativas (era opcional con el cargador [esm] usado en 2019)
import Person from './Person.js';

// clase
class Teacher extends Person {

  // propiedad privada (a la que se accede mediante el getter/setter de abajo)
  private _subject!: string;

  // constructor
  constructor(lastName: string, firstName: string, age: number, subject: string) {
    super(lastName, firstName, age);
    this.subject = subject;
  }

  // getters y setters
  get subject(): string {
    return this._subject;
  }
  set subject(value: string) {
    this._subject = value;
  }

}

// exportación de la clase
export default Teacher;

El script [class-04] usa este tipo de forma polimórfica:

// importaciones
// [actualización 2026] con el ESM nativo de node, la extensión .js es obligatoria
// en las rutas relativas (era opcional con el cargador [esm] usado en 2019)
import Teacher from './Teacher.js';
import Person from './Person.js';

// función que acepta una persona como parámetro
function show(person: Person): void {
  // en todos los casos
  console.log("parameter=", person.toString(), typeof (person));
  // instancia de Person
  if (person instanceof Person) {
    console.log("person=", person.toString());
  }
  // instancia de Teacher
  if (person instanceof Teacher) {
    console.log("teacher=", person.toString());
  }
}

// llamada a show con un docente
show(new Teacher("Poirot", "Hercule", 66, "detective"));
show(new Person("Marple", "Miss", 70));
  • línea 8: function show(person: Person): void : la función espera un parámetro de tipo Person, pero acepta cualquier tipo derivado (Teacher); este es el principio de sustitución, fundamental en la programación orientada a objetos;
  • líneas 11 –18: instanceof permite adaptar el comportamiento al tipo real del objeto recibido, más allá de su tipo declarado.
npx tsx classes/class-04.ts

Resultado de la ejecución:

1
2
3
4
5
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

[NUEVO desde 2019] Los scripts anteriores usan el modificador private (TypeScript, _lastName, _firstName...), un mecanismo de protección que existe solo en tiempo de compilación: en tiempo de ejecución, en JavaScript puro, estos campos siguen siendo simples propiedades normales. Desde ECMAScript 2022 existen verdaderos campos privados, con el prefijo #, que son invisibles e inaccesibles incluso en tiempo de ejecución:

'use strict';
// ========================================================================
// [NUEVO desde 2019] campos privados y bloques estáticos  (ECMAScript 2022)
// ========================================================================

// en class-01.js, el encapsulamiento se simulaba por convención: una propiedad
// llamada [_name] (con un guion bajo) a la que se accedía mediante un getter/setter [name].
// ¡PERO nada impedía realmente escribir person._name = "xyz" desde el exterior!
// desde ECMAScript 2022, podemos declarar campos privados REALES con un [#]
// delante de su nombre: solo son accesibles desde el interior de la clase.

class BankAccount {

  // campo privado: existe y es visible SOLO en los métodos de esta clase
  #balance: number;

  // campo privado con valor por defecto
  #history: string[] = [];

  // campo público normal (sin #): accesible desde el exterior, como antes
  holder: string;

  constructor(holder: string, initialBalance: number = 0) {
    this.holder = holder;
    this.#balance = initialBalance;
  }

  // método público que da acceso controlado al campo privado
  get balance(): number {
    return this.#balance;
  }

  deposit(amount: number): void {
    this.#balance += amount;
    // #addToHistory es un método privado, invocable solo desde aquí
    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: el [#] también funciona con los 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); // mediante el getter público
account.displayHistory();

// no podemos acceder directamente al campo privado desde el exterior
console.log("direct account.#balance : impossible, causes a syntax error if we try");
// console.log(account.#balance); // al quitar el comentario de esta línea se produce un error de compilación de TypeScript

// tampoco podemos leerlo con la notación [ ] como una propiedad normal
console.log("account['#balance'] =", (account as any)["#balance"]); // -> undefined, no es lo mismo

// ------------------------------------------------------------------------
// también existen campos y métodos STATIC privados
// ------------------------------------------------------------------------
class IdGenerator {
  // campo static privado: compartido por todas las instancias, invisible desde el exterior
  static #lastId: number = 0;

  // bloque de inicialización static: se ejecuta una sola vez, cuando se carga la clase
  // útil para una inicialización compleja que un simple "= valor" no permite
  static {
    console.log("[static block] initialization of IdGenerator");
    IdGenerator.#lastId = 1000; // valor inicial personalizado
  }

  // método static público que da acceso controlado al 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] (línea 15), [#history] (línea 18): campos privados verdaderos; a diferencia de _lastName en el script class-01, es imposible acceder a ellos desde fuera de la clase, incluso mediante account['#balance'] (línea 69), que devuelve undefined en lugar del valor real;
  • [#addToHistory] (línea 48): un método privado, que solo puede llamarse desde dentro de la clase;
  • [static { ... }] (líneas 80–83): un bloque de inicialización estático (ES2022), que se ejecuta una sola vez al cargar la clase; es útil para inicializaciones más complejas que una simple asignación;
  • [static #lastId] (línea 76): un campo estático privado, compartido por todas las instancias pero invisible desde el exterior.
npx tsx classes/class-05.ts

Resultado de la ejecución:

1
2
3
4
5
6
7
8
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. Nuevas características de ECMAScript 2020–2024

Los capítulos anteriores ya han cubierto, a medida que avanzábamos, la mayoría de las novedades del lenguaje introducidas desde 2019: encadenamiento opcional y fusión de nulos (basics-09), Object.hasOwn y structuredClone (obj-09), nuevos métodos de arreglos (arr-05), replaceAll/matchAll (str-07), campos privados nativos (class-05), Error con cause (excep-04), await de nivel superior (import-04) y las extensiones de Promise (async-07).

Este capítulo reúne las dos últimas novedades de ECMAScript 2024 que no encajaban en ningún capítulo existente: [Object.groupBy]/[Map.groupBy] y [Array.fromAsync]. El script se encuentra en la carpeta [whats-new] del proyecto.

Image

3.11.1. script [groupBy-and-fromAsync]

'use strict';
// ========================================================================
// [NUEVO desde 2019] Object.groupBy, Map.groupBy, Array.fromAsync (ECMAScript 2024)
// ========================================================================

// ------------------------------------------------------------------------
// 1) Object.groupBy(array, groupingFunction)
// ------------------------------------------------------------------------
// antes, para agrupar los elementos de un arreglo según un criterio, había que
// escribir uno mismo un bucle con 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 antigua, con reduce()
const groupsWithReduce = students.reduce((accumulator: Record<string, Student[]>, student) => {
  const category = student.grade >= 10 ? "passed" : "failed";
  // si todavía no hay un arreglo para esta categoría, lo creamos
  (accumulator[category] ??= []).push(student);
  return accumulator;
}, {});
console.log("with reduce :", groupsWithReduce);

// forma nueva, mucho más legible, con 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 de la misma manera, pero devuelve un [Map] en lugar de un objeto literal
// útil cuando las claves de agrupación no son cadenas (p. ej.: 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) puede construir un arreglo a partir de un iterable síncrono
// Array.fromAsync() puede hacer lo mismo a partir de un iterable ASÍNCRONO,
// es decir, una fuente que produce sus elementos uno a uno, a lo largo del tiempo
// (por ejemplo: la lectura de un flujo de red página por página)

// un generador asíncrono que produce 3 valores, con una pequeña pausa entre cada uno
async function* pageGenerator(): AsyncGenerator<string> {
  for (let i = 1; i <= 3; i++) {
    // simulamos una espera de red antes de cada página
    await new Promise(resolve => setTimeout(resolve, 100));
    yield `page ${i}`;
  }
}

async function demoFromAsync(): Promise<void> {
  console.log("--- Array.fromAsync ---");
  // sin Array.fromAsync, habría hecho falta un bucle "for await...of" manual
  const pages = await Array.fromAsync(pageGenerator());
  console.log("pages =", pages);
}

demoFromAsync();
  • Línea 33: [Object.groupBy(array, groupingFunction)] agrupa los elementos de un arreglo según el resultado de una función de clasificación, lo que es mucho más legible que la construcción manual con reduce() (compare las dos construcciones: líneas 24–29 y línea 33);
  • el resultado de Object.groupBy es un objeto sin prototipo ([Object: null prototype]), un detalle visible en tiempo de ejecución que evita ciertos problemas relacionados con las propiedades heredadas de Object.prototype (como toString, hasOwnProperty...) si una categoría llevara ese nombre;
  • línea 40: [Map.groupBy] funciona de manera idéntica, pero devuelve un Map en lugar de un objeto literal; es indispensable siempre que las claves de agrupación no sean cadenas (en este caso, booleanos);
  • [Array.fromAsync(asyncIterable)] construye un arreglo a partir de una fuente asíncrona, como un generador async function\* , por ejemplo, sin tener que escribir uno mismo un for manual para acumular los resultados.
npx tsx whats-new/groupBy-and-fromAsync.ts

Resultado de la ejecución:

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. Tabla resumen

Resumamos, por versión de ECMAScript, todas las novedades presentadas en este curso desde el capítulo “Fundamentos”:

  • [ES2020]: encadenamiento opcional ?., fusión de nulos ??, BigInt, Promise.allSettled, String.matchAll;
  • [ES2021]: asignación lógica ||=/&&=/??=, separadores numéricos 1_000_000, Promise.any, String.replaceAll;
  • [ES2022]: campos y métodos privados #name, bloques de inicialización estáticos, Object.hasOwn, Array.at, await de nivel superior, Error con cause;
  • [ES2023]: findLast/findLastIndex, métodos inmutables toSorted/toReversed/toSpliced/with;
  • [ES2024]: Object.groupBy/Map.groupBy, Array.fromAsync, Promise.withResolvers, String.isWellFormed/toWellFormed.

Los capítulos siguientes describen las novedades de ECMAScript 2026, así como [Temporal], el reemplazo moderno del objeto Date.

3.12. Novedades de ECMAScript 2026

ECMAScript 2026 (la 17.ª edición del lenguaje) fue finalizado oficialmente por TC39 en 2026. Según el texto oficial de la especificación (https://tc39.es/ecma262/2026/), esta edición agregó: Math.sumPrecise para sumar un conjunto de números minimizando la pérdida de precisión; Iterator.concat para encadenar iteradores; Array.fromAsync (ya presentado en el capítulo anterior); Error.isError para identificar objetos de error de forma confiable; métodos en Map.prototype y WeakMap.prototype para proporcionar un valor predeterminado durante una lectura; métodos en Uint8Array para conversiones hexadecimales y Base64; un parámetro context para los revivers de JSON.parse; y JSON.rawJSON para ajustar con precisión la salida de JSON.stringify.

3.12.1. ⚠️ Una advertencia importante antes de comenzar

La etapa 4 de TC39 garantiza que el comportamiento de una característica ya no cambiará, pero no garantiza su disponibilidad inmediata en todos los motores de JavaScript. Mientras se preparaba este capítulo, un ejemplo concreto lo demostró con claridad: [Math.sumPrecise] produce el error “TypeError: Math.sumPrecise is not a function”, incluso en versiones recientes de Node.js. No se trata de un error de este curso: V8 (el motor que usan Node y Chrome) simplemente aún no ha implementado esta característica, a diferencia de Firefox, Safari y Bun, que ya la tienen (fuente: ticket oficial del repositorio de TypeScript, github.com/microsoft/TypeScript/issues/63427).

Por eso, cada script de este capítulo usa typeof para comprobar por sí mismo si la característica que demuestra está disponible antes de usarla y muestra un mensaje claro si no lo está, en lugar de fallar abruptamente. Esta es en sí misma una buena práctica al usar características muy recientes del lenguaje.

Importante: Todos los scripts de este capítulo se han realmente ejecutado en el entorno de desarrollo de este curso (Node.js 26.7.0); algunos de ellos muestran el mensaje “no disponible”, que es un resultado real y no una suposición. En su máquina, con una versión diferente de Node.js, algunos de estos scripts pueden mostrar un resultado real en lugar de este mensaje; compare con libertad.

Los scripts siguientes se encuentran en la carpeta [ecmascript-2026]:

Image

3.12.2. script [01-math-sumPrecise]

'use strict';
// ========================================================================
// [NUEVO ECMAScript 2026] Math.sumPrecise()
// ========================================================================
// [actualización] en el momento de escribir este script, V8 (y por tanto node y Chrome)
// AÚN NO implementa Math.sumPrecise, mientras que Firefox, Safari y Bun
// ya lo tienen. Este es un ejemplo concreto de la brecha que puede existir entre
// "la funcionalidad ha entrado en la especificación oficial del lenguaje"
// y "todos los motores JavaScript la han implementado realmente": el Stage 4 de TC39
// (alcanzado el 28/07/2025 para esta funcionalidad) garantiza que el
// comportamiento ya no cambiará, pero NO garantiza una disponibilidad
// inmediata en todas partes. Vea ecmascript-2026/README.md para los detalles y las
// fuentes.
// Para comprobar usted mismo si SU node ya tiene esta funcionalidad:
//   node -e "console.log(typeof Math.sumPrecise)"

// sumar números de punto flotante con + acumula errores de redondeo,
// porque cada número se representa de forma imprecisa en binario
const numbers: number[] = [0.1, 0.2, 0.3, 0.1, 0.2, 0.3, 0.1, 0.2, 0.3, 0.1];

// ------------------------------------------------------------------------
// 1) la forma antigua, con reduce(): el resultado no es exacto
// ------------------------------------------------------------------------
const sumWithReduce = numbers.reduce((accumulator, value) => accumulator + value, 0);
console.log("sum with reduce =", sumWithReduce);
// esperamos exactamente 1.9, pero el resultado suele contener decimales espurios
// (p. ej.: 1.9000000000000001) debido a los errores de redondeo que se acumulan en las sumas

// ------------------------------------------------------------------------
// 2) Math.sumPrecise(): suma todos los números de forma exacta
// ------------------------------------------------------------------------
// a diferencia de un bucle de sumas sucesivas, el algoritmo usado internamente
// evita acumular los errores de redondeo intermedios
if (typeof Math.sumPrecise === "function") {
  const preciseSum = Math.sumPrecise(numbers);
  console.log("sum with Math.sumPrecise =", preciseSum);
} else {
  // aquí evitamos un fallo brusco (TypeError) para mantener el carácter didáctico:
  // este mensaje se mostrará mientras su motor JavaScript aún no haya
  // implementado esta funcionalidad, aunque ya esté finalizada en la especificación
  console.log("Math.sumPrecise is not yet available on this JavaScript engine",
    "(see the comment at the top of this file)");
}

// ------------------------------------------------------------------------
// por qué es útil: cálculos financieros, contables, científicos -
// en cualquier lugar donde un pequeño error de redondeo repetido pueda convertirse en un error real
// (p. ej.: el total de una factura que nunca cuadra al centavo)
// ------------------------------------------------------------------------
npx tsx ecmascript-2026/01-math-sumPrecise.ts

Resultado de la ejecución:

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 varios iterables (arreglo, Set, generador, etc.) en un único iterador perezoso: los elementos se generan solo cuando se necesitan, sin construir una colección intermedia completa, a diferencia del operador de propagación [...a, ...b], que copia todo de inmediato en memoria.

'use strict';
// ========================================================================
// [NUEVO ECMAScript 2026] Iterator.concat()
// ========================================================================
// [Node 26+ - mencionado oficialmente en las notas de la versión node 26.0.0:
// ver https://nodejs.org/en/blog/release/v26.0.0 - por lo que normalmente ya está
// disponible si usa node 26. Si no es así, compruébelo con:
//   node -e "console.log(typeof Iterator.concat)"
// vea también ecmascript-2026/README.md para el caso de las demás novedades de
// esta carpeta, que no tienen todas el mismo nivel de disponibilidad]

// a veces tenemos varias fuentes de datos que recorrer una tras otra
// (por ejemplo: varios arreglos, o un arreglo y luego un Set, ...)
const firstWave: string[] = ["Ana", "Léo"];
const secondWave: Set<string> = new Set(["Nora", "Théo"]);
const thirdWave: string[] = ["Zoé"];

// ------------------------------------------------------------------------
// 1) la forma antigua: había que reunir todo en un nuevo arreglo
// ------------------------------------------------------------------------
const allGuestsArray: string[] = [...firstWave, ...secondWave, ...thirdWave];
console.log("with spread :", allGuestsArray);
// inconveniente: esto crea un nuevo arreglo EN MEMORIA con todos los elementos copiados,
// aunque solo necesitemos los 2 primeros (p. ej.: para una visualización paginada)

// ------------------------------------------------------------------------
// 2) Iterator.concat(): encadena los iterables sin copiarlos primero
// ------------------------------------------------------------------------
// Iterator.concat acepta cualquier tipo de iterable (arreglo, Set, Map, generador...)
// y devuelve un iterador "perezoso": los elementos solo se producen a medida que se necesitan
if (typeof Iterator.concat === "function") {
  const allGuests = Iterator.concat(firstWave, secondWave, thirdWave);

  console.log("-----------------------");
  for (const guest of allGuests) {
    console.log("guest =", guest);
  }

  // ------------------------------------------------------------------------
  // ventaja de la pereza: podemos detenernos a mitad de camino
  // sin haber pagado el costo de construir de antemano una colección 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 de la ejecución:

1
2
3
4
5
6
7
8
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 confiable si un valor es un error, incluso cuando proviene de otro "realm" de JavaScript (un contexto de ejecución aislado: un iframe, un worker o el módulo vm de Node.js): cada realm tiene su propia clase Error , lo que hace que instanceof Error falle, como lo demuestra el script en la práctica:

'use strict';
// ========================================================================
// [NUEVO ECMAScript 2026] Error.isError()
// ========================================================================
// [estado de disponibilidad que debe comprobar usted mismo: vea ecmascript-2026/README.md.
// Algunas novedades de ES2026 (como Math.sumPrecise) siguen faltando
// en V8 pese a haber alcanzado el Stage 4 - no es imposible que también sea el caso
// aquí. Compruébelo con: node -e "console.log(typeof Error.isError)"]

// hasta ahora, para saber si un valor es un error, usábamos [instanceof Error]
// (cf. exceptions/excep-03.ts) - esto funciona bien... salvo en algunos casos delicados

// ------------------------------------------------------------------------
// 1) la trampa de [instanceof] con varios "realms" de JavaScript
// ------------------------------------------------------------------------
// un "realm" es un contexto de ejecución de JavaScript aislado: por ejemplo,
// un iframe en un navegador, un worker, o el módulo [vm] de node que permite
// ejecutar código en un contexto separado. Cada realm tiene SU PROPIA clase [Error],
// distinta de la del realm principal.
import vm from 'node:vm';

// ejecutamos "new Error('from elsewhere')" en un realm separado
const errorFromAnotherRealm: unknown = vm.runInNewContext("new Error('from elsewhere')");

console.log("errorFromAnotherRealm =", errorFromAnotherRealm);
// [instanceof Error] falla aquí: NO es la misma clase [Error] que la nuestra,
// aunque el objeto SEA, conceptualmente, un error
console.log("errorFromAnotherRealm instanceof Error :", errorFromAnotherRealm instanceof Error);

// ------------------------------------------------------------------------
// 2) Error.isError(): detección fiable, incluso entre realms distintos
// ------------------------------------------------------------------------
if (typeof Error.isError === "function") {
  console.log("Error.isError(errorFromAnotherRealm) :", Error.isError(errorFromAnotherRealm));

  // a modo de comparación, con un error "normal" (mismo realm), ambas formas de hacerlo
  // dan el mismo resultado
  const normalError = new Error("classic error");
  console.log("normalError instanceof Error :", normalError instanceof Error);
  console.log("Error.isError(normalError) :", Error.isError(normalError));

  // y con un valor que claramente no es un error
  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 de la ejecución:

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 un punto interesante incluso sin que Error.isError esté disponible: la línea errorFromAnotherRealm instanceof Error : false muestra claramente el problema real que Error.isError pretende resolver, aunque el objeto es, conceptualmente, un verdadero error.

3.12.5. script [04-map-weakmap-getOrInsert]

[Map.prototype.getOrInsert]/[getOrInsertComputed] responden a una necesidad muy común: “si la clave ya existe, tomar su valor; en caso contrario, crear un valor predeterminado y almacenarlo”, todo en una sola línea en lugar de un extenso if (!map.has(key)) { map.set(...) }. El mismo principio se aplica a WeakMap.

'use strict';
// ========================================================================
// [NUEVO ECMAScript 2026] Map.prototype.getOrInsert / getOrInsertComputed
// ========================================================================
// [Node 26+ - mencionado oficialmente en las notas de la versión node 26.0.0:
// ver https://nodejs.org/en/blog/release/v26.0.0 - por lo que normalmente ya está
// disponible si usa node 26. Si no es así, compruébelo con:
//   node -e "console.log(typeof Map.prototype.getOrInsert)"
// vea también ecmascript-2026/README.md para el caso de las demás novedades de
// esta carpeta, que no tienen todas el mismo nivel de disponibilidad]

// una necesidad muy frecuente: "si la clave ya existe en el Map, tomar su valor;
// si no, crear un valor por defecto, almacenarlo y luego usarlo"

// ------------------------------------------------------------------------
// 1) la forma antigua: if/has() y luego set() - verboso y fácil de equivocarse
// ------------------------------------------------------------------------
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);
  // aquí se necesita el "!": TypeScript no puede saber, en este punto preciso,
  // que el .get() que sigue a un .set() justo antes tendrá necesariamente éxito
}
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(): lo mismo, en una sola línea
  // ------------------------------------------------------------------------
  const registrations2 = new Map<string, string[]>();

  const register = (workshop: string, participant: string): void => {
    // devuelve el arreglo existente para [workshop], o lo inicializa a [] si aún no existe
    registrations2.getOrInsert(workshop, []).push(participant);
  }
  register("pottery", "Nora");
  register("pottery", "Théo");
  console.log("with getOrInsert :", registrations2);

  // ------------------------------------------------------------------------
  // 3) getOrInsertComputed(): el valor por defecto se calcula SOLO si es necesario
  // ------------------------------------------------------------------------
  // con getOrInsert(key, value), el [value] por defecto se evalúa SIEMPRE,
  // incluso cuando la clave ya existe y no lo necesitamos (aquí no
  // importa para un arreglo vacío [], pero sí puede importar para un cálculo costoso)
  const counters = new Map<string, number>();

  const increment = (key: string): void => {
    // el callback se invoca SOLO si la clave aún no existe en el 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"); // aquí, el callback NO se volverá a ejecutar
  increment("clicks");
  console.log("counters =", counters);

  // ------------------------------------------------------------------------
  // 4) WeakMap.prototype.getOrInsert / getOrInsertComputed: mismo principio,
  // para asociar datos adicionales a objetos sin impedir que el recolector de basura
  // los libere
  // ------------------------------------------------------------------------
  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 de la ejecución:

1
2
3
4
5
6
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 (un arreglo de bytes sin procesar) ahora incluye nuevos métodos para convertir desde y hacia base64 y hexadecimal, formatos que se usan habitualmente para transmitir datos binarios en JSON o en URL, sin depender de un paquete de terceros:

'use strict';
// ========================================================================
// [NUEVO ECMAScript 2026] Uint8Array: conversión a base64 y hexadecimal
// ========================================================================
// [estado de disponibilidad que debe comprobar usted mismo: vea ecmascript-2026/README.md.
// Algunas novedades de ES2026 (como Math.sumPrecise) siguen faltando
// en V8 pese a haber alcanzado el Stage 4 - no es imposible que también sea el caso
// aquí. Compruébelo con: node -e "console.log(typeof Uint8Array.prototype.toBase64)"]

// [Uint8Array] es un arreglo tipado que almacena bytes en bruto (valores 0-255) -
// por ejemplo el contenido de un archivo, una imagen o datos recibidos por la red

// antes de 2026, para codificar estos bytes en base64 (el formato que se usa por ejemplo
// en las URL "data:", o para transmitir datos binarios en JSON),
// había que recurrir a funciones rebuscadas o a paquetes de terceros (buffer en node,
// btoa/atob en el navegador - imperfectos y no diseñados originalmente para eso)

const bytes = new Uint8Array([72, 101, 108, 108, 111]); // "Hello" en 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) codificación base64
  // ------------------------------------------------------------------------
  const inBase64 = bytes.toBase64();
  console.log("bytes in base64 =", inBase64);

  // decodificación: reconstruir un Uint8Array a partir de una cadena base64
  const recoveredBytes = Uint8Array.fromBase64(inBase64);
  console.log("recovered bytes =", recoveredBytes);
  console.log("identical to the original :", bytes.toString() === recoveredBytes.toString());

  // ------------------------------------------------------------------------
  // 2) codificación hexadecimal
  // ------------------------------------------------------------------------
  const inHexadecimal = bytes.toHex();
  console.log("bytes in hexadecimal =", inHexadecimal);

  const bytesFromHex = Uint8Array.fromHex(inHexadecimal);
  console.log("bytes from hex =", bytesFromHex);

  // ------------------------------------------------------------------------
  // 3) llenar un Uint8Array existente, a partir de un desplazamiento dado
  // ------------------------------------------------------------------------
  // útil para ensamblar varios fragmentos en el mismo búfer, sin asignaciones
  // intermedias
  const buffer = new Uint8Array(10);
  const writeResult = buffer.setFromHex("48656c6c6f"); // "Hello" en hexadecimal
  console.log("buffer after setFromHex =", buffer);
  console.log("characters read / written =", writeResult);
}

// ------------------------------------------------------------------------
// por qué es útil: transmitir datos binarios en formatos de texto
// (JSON, URL, encabezados HTTP...), sin depender de un paquete de terceros ni de trucos
// ------------------------------------------------------------------------
npx tsx ecmascript-2026/05-uint8array-base64-hex.ts

Resultado de la ejecución:

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 se diferencia de los anteriores: [JSON.rawJSON]/[isRawJSON], así como el nuevo parámetro "context" del reviver de JSON.parse, ya funcionan con Node 22 (las salidas de este capítulo se obtuvieron con Node 26):

'use strict';
// ========================================================================
// [NUEVO ECMAScript 2026] JSON.rawJSON / JSON.isRawJSON, y el contexto del reviver
// ========================================================================
// [estas dos nuevas funcionalidades ya funcionan con node 22, a diferencia de los demás
// scripts de esta carpeta que requieren node 24 - vea ecmascript-2026/README.md]

// ------------------------------------------------------------------------
// 1) el problema: JSON.stringify pierde precisión con los enteros grandes
// ------------------------------------------------------------------------
// un number clásico de JavaScript (tipo [number]) no puede representar
// exactamente los enteros que superan Number.MAX_SAFE_INTEGER (cf. basics/basics-09.ts)
// sin embargo, muchas API (bases de datos, redes sociales, ...) envían
// identificadores numéricos de 17 a 19 dígitos en su JSON
const databaseColumnIdentifier = "9007199254740993123"; // demasiado grande para un [number]

interface DataRecord {
  id: unknown; // desconocido aquí porque será o bien un RawJSON, o bien un valor normal
  name: string;
}

// ------------------------------------------------------------------------
// 2) JSON.rawJSON(): inserta un número "en bruto" en un JSON.stringify,
//    sin pasarlo nunca por el tipo [number] (y por tanto sin pérdida de precisión)
// ------------------------------------------------------------------------
const record: DataRecord = {
  id: JSON.rawJSON(databaseColumnIdentifier),
  name: "temperature-sensor-3"
};

const jsonText = JSON.stringify(record);
console.log("jsonText =", jsonText);
// el identificador aparece tal cual en el texto producido, dígito por dígito,
// mientras que un id: Number(databaseColumnIdentifier) habría sido redondeado

// JSON.isRawJSON() permite comprobar si un valor fue creado por JSON.rawJSON
console.log("JSON.isRawJSON(record.id) =", JSON.isRawJSON(record.id));

// ------------------------------------------------------------------------
// 3) el reviver de JSON.parse ahora recibe un 3.er parámetro [context]
// ------------------------------------------------------------------------
// antes de 2026, el reviver solo recibía (key, value): era imposible saber
// cuál era el texto JSON EXACTO del que provenía este valor (útil precisamente
// para recuperar un número grande sin pérdida, conservándolo como texto)
const reReadObject = JSON.parse(jsonText, (key, value, context) => {
  // [context.source] da el texto JSON en bruto correspondiente a este valor,
  // antes de cualquier conversión a un tipo JavaScript - undefined para objetos/arreglos
  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)] inserta un número “sin procesar” en JSON.stringify sin convertirlo nunca al tipo number ; es útil para identificadores numéricos muy grandes (superiores a Number.MAX_SAFE_INTEGER, véase basics-09) que, de otro modo, perderían precisión;
  • el tercer parámetro, context, de la función reviver da acceso, mediante context.source, al texto JSON sin procesar del valor que se está procesando, antes de cualquier conversión a un tipo de JavaScript.
npx tsx ecmascript-2026/06-json-rawJSON-and-reviver.ts

Resultado de la ejecución:

1
2
3
4
5
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' }

Se aprecia claramente la ventaja de JSON.rawJSON: el texto JSON resultante conserva el identificador dígito por dígito (9007199254740993123), mientras que un simple id: Number(...) lo habría redondeado, como lo demuestra el valor devuelto por JSON.parse (9007199254740993000), que sí se convirtió al tipo number y perdió precisión.

3.13. Temporal: el reemplazo moderno de Date

[Temporal] es un nuevo espacio de nombres global destinado a reemplazar al antiguo objeto Date, considerado defectuoso desde hace mucho tiempo: mutabilidad, meses numerados de 0 a 11, falta de un verdadero manejo de zonas horarias y análisis ambiguo de cadenas. Date no ha sido eliminado del lenguaje (el código existente sigue funcionando), pero Temporal es ahora el enfoque recomendado para cualquier código nuevo que manipule fechas, horas y duraciones.

3.13.1. ⚠️ Estado exacto respecto de ECMAScript 2026

La propuesta Temporal alcanzó la etapa 4 de TC39 en marzo de 2026, y numerosos artículos la han presentado como parte de ECMAScript 2026. Sin embargo, la sección oficial de la especificación que resume el contenido de ECMAScript 2026 (citada en el capítulo anterior) no la menciona explícitamente; la cuestión queda por aclarar. En términos prácticos, Temporal está disponible de forma nativa en Node.js 26 y en los navegadores actualizados, lo que hace que este capítulo sea pertinente desde ya.

Los scripts siguientes se encuentran en la carpeta [temporal]:

Image

3.13.2. script [01-plainDate-plainTime-plainDateTime]

Este script demuestra [Temporal.PlainDate] (una fecha sin hora ni zona horaria), [Temporal.PlainTime] (una hora sin fecha) y [Temporal.PlainDateTime] (fecha + hora, sin zona horaria):

'use strict';
// ========================================================================
// [NUEVO ECMAScript 2026] Temporal: PlainDate, PlainTime, PlainDateTime
// ========================================================================
// [requiere Node 26+ - vea temporal/README.md]

// [Temporal] es un espacio de nombres totalmente nuevo, diseñado para reemplazar a [Date],
// que adolecía de varios defectos: mutabilidad, meses numerados de 0 a 11
// (¡enero = 0!), ningún manejo real de zonas horarias y un
// único objeto que debía representar a la vez una fecha, una hora Y un instante.
// Temporal separa claramente estas nociones en varios tipos.

// ------------------------------------------------------------------------
// 1) Temporal.PlainDate: una fecha SIN hora ni zona horaria
// ------------------------------------------------------------------------
// útil para: un cumpleaños, una fecha de vencimiento, un día festivo...
// nociones que no tienen un "momento preciso del día"
const birthday = Temporal.PlainDate.from("2026-08-24");
console.log("birthday =", birthday.toString());
console.log("year =", birthday.year, ", month =", birthday.month, ", day =", birthday.day);
// a diferencia del antiguo Date, el mes se numera normalmente: 8 = agosto (¡no 7!)
console.log("day of the week (1=Monday..7=Sunday) =", birthday.dayOfWeek);
console.log("number of days in this month =", birthday.daysInMonth);

// ------------------------------------------------------------------------
// 2) inmutabilidad: add() y subtract() devuelven un objeto NUEVO
// ------------------------------------------------------------------------
// con el antiguo Date, date.setDate(date.getDate() + 7) modifica el objeto en su lugar -
// una fuente clásica de errores cuando este objeto se comparte en otra parte del código
const inOneWeek = birthday.add({ days: 7 });
console.log("birthday (unchanged) =", birthday.toString());
console.log("inOneWeek (new object) =", inOneWeek.toString());

// aritmética con meses: maneja automáticamente el número de días del mes siguiente
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" y no un extraño desbordamiento hacia marzo, a diferencia del antiguo Date

// ------------------------------------------------------------------------
// 3) comparación de dos fechas
// ------------------------------------------------------------------------
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"));

// duración entre dos fechas
const duration = birthday.until(backToSchool);
console.log("duration until back to school =", duration.toString());

// ------------------------------------------------------------------------
// 4) Temporal.PlainTime: una hora SIN fecha ni zona horaria
// ------------------------------------------------------------------------
// útil para: "la clase empieza a las 2:30 pm", sin importar el día
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: fecha + hora, pero SIN zona horaria
// ------------------------------------------------------------------------
// útil para: una cita "civil" sin preocuparse por la zona horaria (p. ej.: un formulario
// que solo muestra "24/08/2026 14:30" sin precisar dónde)
const appointment = Temporal.PlainDateTime.from("2026-08-24T14:30:00");
console.log("appointment =", appointment.toString());
// podemos extraer por separado la parte de la fecha y la parte de la hora
console.log("date part =", appointment.toPlainDate().toString());
console.log("time part =", appointment.toPlainTime().toString());
  • A diferencia del antiguo objeto Date, el mes en Temporal.PlainDate se numera de forma normal: 8 corresponde a agosto, no a julio;
  • [inmutabilidad]: add() y subtract() siempre devuelven un objeto nuevo; el original nunca se modifica, a diferencia de Date.prototype.setDate;
  • las operaciones aritméticas con meses manejan automáticamente la distinta duración de los meses (31 de enero + 1 mes da efectivamente el 28 de febrero, y no un desbordamiento hacia marzo);
  • Temporal.PlainDate.compare(...) y .until(...) permiten comparar dos fechas y calcular la duración entre ellas.

3.13.3. script [02-zonedDateTime]

[Temporal.ZonedDateTime] es el tipo más parecido al antiguo Date: combina fecha, hora y zona horaria de forma confiable y explícita:

'use strict';
// ========================================================================
// [NUEVO ECMAScript 2026] Temporal.ZonedDateTime: el verdadero reemplazo de Date
// ========================================================================
// [requiere Node 26+ - vea temporal/README.md]

// [Temporal.ZonedDateTime] es el tipo más cercano al antiguo [Date]:
// combina una fecha, una hora Y una zona horaria - pero de forma fiable
// y explícita, mientras que [Date] lo manejaba de forma confusa e implícita.

// ------------------------------------------------------------------------
// 1) creación de un ZonedDateTime, con una zona horaria EXPLÍCITA
// ------------------------------------------------------------------------
// a diferencia de "new Date('2026-08-24T14:30:00')", que es ambiguo (¿hora local?
// ¿UTC? ¡depende del formato y del motor de JS!), aquí la zona horaria es obligatoria
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) conversión de la misma reunión a otra zona horaria
// ------------------------------------------------------------------------
// withTimeZone() NO cambia el instante real, solo la forma de mostrarlo -
// útil para mostrar la hora del mismo evento a participantes de todo el mundo
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) la aritmética maneja automáticamente los cambios de horario de verano (DST)
// ------------------------------------------------------------------------
// esta es LA trampa clásica del antiguo Date: sumar "24 horas" no siempre
// equivale a sumar "1 día" durante un cambio de horario de verano/invierno
const beforeTimeChange = Temporal.ZonedDateTime.from("2026-10-24T20:00:00[Europe/Paris]");
// sumamos un día "calendario": Temporal entiende que hay que saltarse el cambio de hora
const oneDayLater = beforeTimeChange.add({ days: 1 });
console.log("before =", beforeTimeChange.toString());
console.log("+ 1 calendar day =", oneDayLater.toString());
// sumamos exactamente 24 horas: esta NO es necesariamente la misma hora local
// si entre medias hubo un cambio de horario de verano/invierno
const twentyFourHoursLater = beforeTimeChange.add({ hours: 24 });
console.log("+ exactly 24 hours =", twentyFourHoursLater.toString());

// ------------------------------------------------------------------------
// 4) la hora actual, en la zona horaria del sistema
// ------------------------------------------------------------------------
const now = Temporal.Now.zonedDateTimeISO();
console.log("now =", now.toString());
console.log("system time zone =", Temporal.Now.timeZoneId());

// ------------------------------------------------------------------------
// 5) comparación y duración entre dos ZonedDateTime de zonas horarias distintas
// ------------------------------------------------------------------------
const planeDeparture = Temporal.ZonedDateTime.from("2026-12-20T22:00:00[Europe/Paris]");
const planeArrival = Temporal.ZonedDateTime.from("2026-12-21T11:30:00[Asia/Tokyo]");
// Temporal compara los instantes reales, sin importar la zona horaria mostrada en cada lado
const flightDuration = planeDeparture.until(planeArrival);
console.log("flight duration =", flightDuration.toString());
  • a diferencia de new Date('2026-08-24T14:30:00'), cuya interpretación (hora local o UTC) depende del formato exacto de la cadena, Temporal.ZonedDateTime.from(...) exige una zona horaria explícita, escrita entre corchetes;
  • withTimeZone(...) convierte la visualización de la misma hora real a otra zona horaria sin cambiar el instante en sí; es útil para mostrar la hora de una reunión a participantes de varios países;
  • la aritmética maneja correctamente los cambios de horario de verano: sumar “1 día calendario” no siempre equivale a sumar “exactamente 24 horas”, una trampa clásica de la antigua función Date.

3.13.4. script [03-duration-and-instant]

[Temporal.Duration] representa un lapso de tiempo (no un momento específico); [Temporal.Instant] representa un punto específico y universal en el tiempo, el reemplazo directo de new Date(...).getTime():

'use strict';
// ========================================================================
// [NUEVO ECMAScript 2026] Temporal.Duration y Temporal.Instant
// ========================================================================
// [requiere Node 26+ - vea temporal/README.md]

// ------------------------------------------------------------------------
// 1) Temporal.Duration: representa un LAPSO de tiempo (no un momento preciso)
// ------------------------------------------------------------------------
// antes, había que armar una duración "a mano" en milisegundos -
// poco legible, y sin distinción entre unidades de calendario (meses, años)
// y unidades fijas (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);

// una duración también se puede crear a partir de su notación ISO 8601
const worksDuration = Temporal.Duration.from("P3M2W"); // 3 meses y 2 semanas
console.log("worksDuration =", worksDuration.toString());

// total() convierte una duración completa a una sola unidad
console.log("tripDuration in minutes =", tripDuration.total("minutes"));

// ------------------------------------------------------------------------
// 2) suma de una duración a una fecha o a una 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: un punto en el tiempo PRECISO y UNIVERSAL
// ------------------------------------------------------------------------
// a diferencia de PlainDateTime o ZonedDateTime (que tienen una noción de calendario
// y de zona horaria), Instant solo representa "un instante", como un timestamp -
// es el reemplazo directo de "new Date(something).getTime()"
const now = Temporal.Now.instant();
console.log("now (Instant) =", now.toString());
console.log("epoch in milliseconds =", now.epochMilliseconds);

// un Instant se puede convertir a un ZonedDateTime en cualquier zona horaria,
// ya que un instante preciso corresponde a una hora local distinta según la zona horaria
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) duración entre dos instantes, y comparación
// ------------------------------------------------------------------------
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);
  • Una Duration puede construirse a partir de un objeto ({ hours: 2, minutes: 45 }) o de una cadena en formato ISO 8601 (por ejemplo, "P3M2W" para 3 meses y 2 semanas);
  • total(unit) convierte una duración completa a una sola unidad (por ejemplo, minutos);
  • Un mismo Instant puede convertirse a ZonedDateTime en cualquier zona horaria; un instante específico corresponde a una hora local distinta según el lugar en que usted se encuentre.

3.13.5. script [04-comparison-with-Date]

Este script aborda, uno por uno, los defectos históricos de Date mencionados en la introducción y muestra cómo Temporal los corrige:

'use strict';
// ========================================================================
// [NUEVO ECMAScript 2026] Temporal frente a Date: las trampas clásicas corregidas
// ========================================================================
// [requiere Node 26+ - vea temporal/README.md]

// [Date] no se elimina del lenguaje (el código existente sigue funcionando),
// pero [Temporal] es ahora la API recomendada para cualquier código nuevo.
// este script ilustra, una por una, las fallas históricas de [Date].

// ------------------------------------------------------------------------
// trampa n.º 1: meses numerados de 0 a 11 en Date (¡enero = 0!)
// ------------------------------------------------------------------------
const augustDate = new Date(2026, 7, 24); // ¿7 = agosto?! muy confuso para un principiante
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)");

// ------------------------------------------------------------------------
// trampa n.º 2: Date es mutable - un objeto compartido puede modificarse por error
// ------------------------------------------------------------------------
function addOneWeekDate(date: Date): Date {
  date.setDate(date.getDate() + 7); // ¡modifica el objeto recibido como parámetro!
  return date;
}
const originalDate = new Date(2026, 7, 24);
const dateWithOneMoreWeek = addOneWeekDate(originalDate);
// trampa: originalDate también ha sido modificado, cuando esto no era necesariamente lo deseado
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 }); // devuelve un objeto NUEVO, no 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());

// ------------------------------------------------------------------------
// trampa n.º 3: el análisis de una cadena de caracteres con Date es ambiguo
// ------------------------------------------------------------------------
// según el formato de la cadena, "new Date(...)" la interpreta a veces como hora local,
// a veces como UTC - una trampa frecuente en producción
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)");
// -> ¡las dos líneas de arriba pueden mostrar horas distintas, para la "misma" fecha!

// con Temporal, el comportamiento es siempre explícito e inequívoco:
// un PlainDate no tiene ninguna hora, un ZonedDateTime exige una zona horaria precisa
console.log("[Temporal] PlainDate.from('2026-08-24') =", Temporal.PlainDate.from("2026-08-24").toString());

// ------------------------------------------------------------------------
// trampa n.º 4: Date no puede calcular de forma nativa una duración "limpia"
// ------------------------------------------------------------------------
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());

// ------------------------------------------------------------------------
// en resumen: Temporal es inmutable, sin ambigüedad de zona horaria, con
// tipos separados para cada uso (solo fecha, solo hora, instante preciso,
// fecha+hora+zona...), y una aritmética fiable incluso en torno a los cambios
// de horario de verano y a meses de distinta duración.
// ------------------------------------------------------------------------
  • [trampa n.º 1]: los meses de Date se numeran de 0 a 11 (aunque new Date(2026, 7, 24) corresponde efectivamente a agosto), una fuente común de confusión para los principiantes;
  • [trampa n.º 2]: Date es mutable: modificar un objeto Date pasado como parámetro de una función también modifica el original, lo que puede resultar sorprendente; Temporal.PlainDate.add() siempre devuelve un objeto nuevo;
  • [trampa n.º 3]: el análisis de una cadena con new Date(...) es ambiguo según su formato exacto (hora local o UTC); Temporal siempre es explícito;
  • [trampa n.º 4]: Date no puede calcular de forma nativa una duración “limpia” entre dos fechas (hay que restar marcas de tiempo en milisegundos y dividir manualmente); Temporal.PlainDate.until(...) lo hace directamente.