Office Scripts: las Arrays

Sin duda he sido siempre un 'enamorado' de las Arrays en VBA... y por simpatía, lo soy de las Arrays en Typescript (Office Scripts).
Las matrices nos permiten trabajar de formas distintas, aportándonos propiedades o métodos no disponibles en otros objetos (por ejemplo, los rangos)... por lo que siempre es buena idea estar familiarizados con ellas....

Debemos entender una Array como una colección de valores, que normalmente deben ser además del mismo tipo.

Empezaremos por determinar cómo declarar e inicializar una Array.
La forma más habitual es:

let arrnumeros: number[]; //declaración
  arrnumeros= [1,3,5];      //carga de datos o inicialización
  // o también en la misma línea
  let arrnumeros:number[]=[1,3,5];
  // o alternativamente de una forma más ortodoxa
  let arrnumeros: number[] = new Array(1, 3, 5);

Otro aspecto importante es cómo podemos acceder a esa matriz y recuperar alguno de sus datos.
para esto solo tenemos que referirnos al nombre de la Array declarado y entre corchetes indicar el número/posición del elemento a recuperar (OJOOOO, nos movemos en base cero!!).

 let arrnumeros: number[] = new Array(1, 3, 5);
  console.log (arrnumeros[2]);

que nos devolverá el TERCER elemento de nuestra Array!.

Pero como comentaba al inicio del artículo, la gran ventaja de las Arrays son los distintos métodos y/o propiedades de que disponen. Que a modo de resumen y en orden alfabético son:
I. miArray.concat(value1, value2, ..., valueN):
Devueve una nueva Array compuesta de los valores dados.
II. miArray.every(función_a _aplicar_a_cada_elemento, [opcional Objeto X])
Devuelve true si todos y cada uno de los elementos de la Array cumple la función dada.
III. miArray.filter(función_a _aplicar_a_cada_elemento, [opcional Objeto X]) Retorna una nueva Array con aquellos elementos que satisfagan la función dada.
IV. miArray.forEach(función_a _aplicar_a_cada_elemento, [opcional Objeto X]) Aplica a cada elemento la función dada.
V. miArray.indexOf(elemento_buscado, [opcional Base de numeración (0 por defecto)]) Obtenemos la posición del elemento buscado (la primera coincidencia!!) dentro de la Array. Devolverá -1 si no lo encuentra.
VI. miArray.join(separador) Concatena o une todos los elementos de la Array con el separador dado, retornando una cadena de texto.
VII. miArray.lastIndexOf(elemento_buscado, [opcional Base de numeración (0 por defecto)]) Obtenemos la posición del elemento buscado (la última coincidencia!!) dentro de la Array. Devolverá -1 si no lo encuentra.
VIII. miArray.map(función_a _aplicar_a_cada_elemento, [opcional Objeto X]) Crea una nueva Array con el resultado devuelto tras aplciar a cada elemento la función dada.
IX. miArray.pop() Elimina el último elemento de la Array, y además nos devuelve dicho elemento.
X. miArray.push(elemento1, ..., elementoN) Agregamos uno o más nuevos elementos al final de la Array, devolviendo además el nuevo tamaño.
XI. miArray.reduce(función_a _aplicar_a_cada_elemento, [opcional Valor Inicial]) Aplica la función dada al mismo tiempo contra dos elementos de la Array (de izquierda a derecha) hasta reducirlo a un único elemento.
XII. miArray.reduceRight() Igual que la anterior pero de derecha a izquierda.
XIII. miArray.reverse() Invierte el orden de los elementos.
XIV. miArray.shift() Elimina el primer elemento de la Array, y además nos devuelve dicho elemento.
XV. miArray.slice(inicio, [fin]) Devuelve una nueva Array con los elementos extraidos desde la posición de inicio hasta la de fin.
XVI. miArray.some(función_a _aplicar_a_cada_elemento, [opcional Objeto X]) Retorna true conque al menos uno de los elementos de la Array cumpla la función dada.
XVII. miArray.sort(Función_de_comparación) Devuelve una Array ordenada según la función dada... si omitimos la función se ordenan alfabéticamente.
XVIII. miArray.splice(index, cuántos, [opcional elemento1][opcionales , ..., elementoN]) Agrega y/o elimina elementos de la Array.
XIX. miArray.toString() Recuperamos una cadena de texto compuesta por los elementos de la Array.
XX. miArray.unshift(elemento1, ..., elementoN) Agregamos uno o más nuevos elementos al principio de la Array, devolviendo además el nuevo tamaño.

Sirvan a modo de introducción...
Un ejemplo de algunos de estos puntos comentados:

function main(workbook: ExcelScript.Workbook) {
  //crear Array vacía
  //let vacia:string[] = new Array();
  let vacia: string[] = [];   //alternativamente...
  console.log('"vacia" tiene:= num columnas ' + vacia[0]?.length + ' ' + 'num filas ' + vacia.length);

  //podemos definir una Array simple de una dimensión
  //let simple:string[] = new Array("ES","FR","IT","DE");
  let simple: string[] = [`ES`, `FR`, `IT`, `DE`] ;
  console.log('"simple" tiene:= num columnas ' + simple[0].length + ' ' + '\n num filas ' + simple.length);
  console.log('el array "simple" dispuesto: ' + simple);
  //podemos recuperar cualquiera de sus elementos (recuerda que nos movemos en base cero)
  console.log('el tercer elemento (base cero!) del array "simple": ' + simple[2]);

  //cambio el tamaño de la Array
  simple.length=2;  //OJO!, lenght permite redimensionar una Array
  console.log('el array "simple" modificado: ' + simple);
  simple[2]="UK";   //añadimos un elemento nuevo...
  console.log('el array "simple" con nuevo dato: ' + simple);

  //de forma similar con métodos como shift/unshift push/pop
  //que eliminan o agregan elementos por el principio o final de la Array
  simple.pop();   //elimina el último elemento
  console.log('el array "simple" despues de borrar el último elemento con pop: ' + simple);
  simple.shift(); //elimina el primer elemento
  console.log('el array "simple" despues de borrar el primer elemento con shift: ' + simple);
  simple.push('US');  //añade nuevo elemento al final
  console.log('el array "simple" despues de añadir nuevo elemento al final con push: ' + simple);
  simple.unshift('PT');   //añade nuevo elemento al inicio de la Array
  console.log('el array "simple" despues de añadir nuevo elemento al inico con unshift: ' + simple);

  //podemos ordenar nuestra Array con el método sort (en ASC por defecto) y reverse para invertir orden
  console.log("Array ordenada:= " + simple.sort());
  console.log("Array en orden inverso:= " + simple.reverse());

  //método join para unir los elementos del Array
  console.log("Array con sus elementos unidos:= " + simple.join(' y '));


  //o Arrays de 2D...
  let encab: string[][] = [['Fechas', 'País', 'Producto', 'Unidades']];

  console.log('"encab" tiene:= num columnas ' + encab[0].length + ' ' + 'num filas ' + encab.length);
  console.log('el array "encab" dispuesto: ' + encab);
}

Si vemos lo obtenido en el apartado de la 'consola' tendríamos:

"vacia" tiene:= num columnas undefined num filas 0
"simple" tiene:= num columnas 2 
 num filas 4
el array "simple" dispuesto: ES,FR,IT,DE
el tercer elemento (base cero!) del array "simple": IT
el array "simple" modificado: ES,FR
el array "simple" con nuevo dato: ES,FR,UK
el array "simple" despues de borrar el último elemento con pop: ES,FR
el array "simple" despues de borrar el primer elemento con shift: FR
el array "simple" despues de añadir nuevo elemento al final con push: FR,US
el array "simple" despues de añadir nuevo elemento al inico con unshift: PT,FR,US
Array ordenada:= FR,PT,US
Array en orden inverso:= US,PT,FR
Array con sus elementos unidos:= US y PT y FR
"encab" tiene:= num columnas 4 num filas 1
el array "encab" dispuesto: Fechas,País,Producto,Unidades

Finalizar con un nombre raro a priori, pero de concepto simple: las tuplas. Una tupla es una Array pero con elementos con diferente tipo de datos.
Por suerte nos servirán igualmente todos los aspectos comentados (creación, métodos, etc...)