Este archivo contiene una coleción de utilidades para la manipulación de arrays en JavaScript, facilitendo diversas operaciones comunes.

Ejemplo de uso:

import utilsArray from '@/utils/arrayUtils.js';
const items = ['manzana', 'banana', 'cereza', 'dátil', 'elderberry'];
// Seleccionar aleatoriamente dos elementos del array
const randomSelection = utilsArray.getRandomElements(items, 2);
 

Funciones Personalizadas

/**
* @name utilsArray.isArray(value)
* @description Verifica si un valor es un array.
* @param {*} value - El valor a verificar.
* @returns {boolean} - Verdadero si el valor es un array, falso en caso contrario.
*/
 

/**
* @name utilsArray.countOccurrences(element, array)
* @description Cuenta cuántas veces aparece un elemento específico en un array.
* @param {*} element - El elemento a buscar.
* @param {Array} array - El array donde buscar.
* @returns {number} - El número de ocurrencias del elemento.
*/
 

/**
* @name utilsArray.insertElement(array, index, element)
* @description Inserta un elemento en una posición específica de un array sin modificar el original.
* @param {Array} array - El array base.
* @param {number} index - La posición donde insertar el elemento (basado en 0).
* @param {*} element - El elemento a insertar.
* @returns {Array} - Un nuevo array con el elemento insertado.
*/
 

/**
* @name utilsArray.removeDuplicates(array)
* @description Devuelve un nuevo array eliminando elementos duplicados.
* @param {Array} array - El array de entrada.
* @returns {Array} - Un nuevo array sin duplicados.
*/
 

/**
* @name utilsArray.getRandomElements(array, numElements)
* @description Extrae elementos aleatorios de un array.
* @param {Array} array - El array del cual extraer los elementos.
* @param {number} [numElements] - El número de elementos a extraer. Si no se especifica, se extrae uno.
* @returns {*|Array} - Si numElements es 1 o no se especifica, devuelve el elemento. Si numElements es mayor que 1, devuelve un array con los elementos extraídos.
*/
 

/**
* @name utilsArray.sortAscending(array, key)
* @description Ordena un array de forma ascendente.
* @param {Array} array - El array a ordenar. Soporta strings, números, objetos y fechas.
* @param {string} [key] - La clave a utilizar para ordenar si los elementos son objetos.
* @returns {Array} - El array ordenado ascendentemente.
*
* @name utilsArray.sortDescending(array, key)
* @description Ordena un array de forma descendente.
* @param {Array} array - El array a ordenar. Soporta strings, números, objetos y fechas.
* @param {string} [key] - La clave a utilizar para ordenar si los elementos son objetos.
* @returns {Array} - El array ordenado descendentemente.
*
* @example
* const numbers = [1, 56, 12, 68, 10];
* const ascNumbers = utilsArray.sortAscending(numbers);
*
* const objects = [{id: 312, name: 'Alice'}, {id: 21, name: 'Bob'}];
* const ascObjects = utilsArray.sortAscending(objects, 'id');
*/
 

/**
* @name utilsArray.shuffleArray(array)
* @description Devuelve una versión aleatoriamente desordenada del array.
* @param {Array} array - El array a desordenar.
* @returns {Array} - El array desordenado.
*/
 

Métodos Nativos de Array

/**
* @name array.length
* @description Devuelve la longitud del array.
* @returns {number} - La longitud del array.
*/
 

/**
* @name array.join(separator)
* @description Convierte un array en una cadena de texto, uniendo los elementos con un separador especificado.
* @param {string} [separator] - El separador a usar entre elementos.
* @returns {string} - La cadena resultante.
*/
 

/**
* @name array.reverse()
* @description Invierte el orden de los elementos en un array. Este método modifica el array original.
* @returns {Array} - El array invertido.
*/
 

/**
* @name string.split(separator, limit)
* @description Divide una cadena en un array de subcadenas.
* @param {string|RegExp} [separator] - El patrón donde dividir la cadena.
* @param {number} [limit] - El número máximo de divisiones a realizar.
* @returns {Array} - Un array de subcadenas.
*/
 

Métodos para Añadir/Eliminar Elementos

/**
* @name array.concat(array1, array2, ...)
* @description Combina arrays o valores al final de un array existente, devolviendo un nuevo array. No modifica el array original.
* @returns {Array} - Un nuevo array combinado.
*/
 

/**
* @name array.push(element1, element2, ...)
* @description Añade uno o más elementos al final de un array. Modifica el array original.
* @returns {number} - La nueva longitud del array.
*/
 

/**
* @name array.unshift(element1, element2, ...)
* @description Añade uno o más elementos al principio de un array. Modifica el array original.
* @returns {number} - La nueva longitud del array.
*/
 

/**
* @name array.splice(startIndex, deleteCount, item1, item2, ...)
* @description Añade o elimina elementos de un array en una posición específica. Modifica el array original.
* @param {number} startIndex - La posición donde empezar a modificar.
* @param {number} [deleteCount] - El número de elementos a eliminar. Si se omite, se eliminan todos los elementos desde startIndex.
* @param {...*} item1, ...itemX - Los elementos a añadir en la posición de inicio.
* @returns {Array} - Un array con los elementos eliminados.
*/
 

/**
* @name array.slice(startIndex, endIndex)
* @description Devuelve una porción (copia superficial) de un array en una nueva matriz. No modifica el array original.
* @param {number} [startIndex] - Índice donde empezar la extracción. Si es negativo, indica una posición relativa al final del array.
* @param {number} [endIndex] - Índice donde terminar la extracción (no incluido). Si es negativo, indica una posición relativa al final del array.
* @returns {Array} - Un nuevo array con la porción seleccionada.
*/
 

Métodos de Filtrado y Procesamiento de Elementos

// Iterar sobre los elementos de un array
array.forEach((element, index) => {
 // Código a ejecutar para cada elemento
});
 

/**
* @name array.every(callbackFn)
* @description Prueba si todos los elementos en el array cumplen con la condición implementada por la función proporcionada.
* @param {function(element, index, array): boolean} callbackFn - Función a ejecutar para cada elemento. Debe retornar true o false.
* @returns {boolean} - Verdadero si todos los elementos pasan la prueba, falso en caso contrario.
*
* @example
* const numbers = [2, 4, 6, 8];
* const allEven = numbers.every(num => num % 2 === 0); // true
*/
 

/**
* @name array.some(callbackFn)
* @description Prueba si al menos un elemento en el array cumple con la condición implementada por la función proporcionada.
* @param {function(element, index, array): boolean} callbackFn - Función a ejecutar para cada elemento. Debe retornar true o false.
* @returns {boolean} - Verdadero si al menos un elemento pasa la prueba, falso en caso contrario.
*
* @example
* const numbers = [1, 3, 5, 8];
* const hasEven = numbers.some(num => num % 2 === 0); // true
*/
 

/**
* @name array.map(callbackFn)
* @description Crea un nuevo array con los resultados de llamar a una función proporcionada en cada elemento del array original.
* @param {function(element, index, array): any} callbackFn - Función a ejecutar para cada elemento. El valor retornado se usará para el nuevo array.
* @returns {Array} - Un nuevo array con los elementos transformados.
*
* @example
* const numbers = [1, 2, 3];
* const doubled = numbers.map(num => num * 2); // [2, 4, 6]
*/
 

/**
* @name array.filter(callbackFn)
* @description Crea un nuevo array con todos los elementos que pasan la prueba implementada por la función proporcionada.
* @param {function(element, index, array): boolean} callbackFn - Función a ejecutar para cada elemento. Debe retornar true para mantener el elemento, false para descartarlo.
* @returns {Array} - Un nuevo array con los elementos filtrados.
*
* @example
* const numbers = [1, 2, 3, 4, 5];
* const greaterThanThree = numbers.filter(num => num > 3); // [4, 5]
*/
 

/**
* @name array.reduce(callbackFn, initialValue)
* @description Ejecuta una función reductora sobre cada elemento del array, a fin de reducirlo a un único valor.
* @param {function(accumulator, currentValue, index, array): any} callbackFn - Función reductora. El `accumulator` es el valor acumulado.
* @param {*} [initialValue] - Valor inicial del `accumulator`. Si no se proporciona, el primer elemento del array se usa como valor inicial y la iteración comienza desde el segundo elemento.
* @returns {any} - El valor final resultante de la reducción.
*
* @example
* const numbers = [1, 2, 3, 4];
* const sum = numbers.reduce((acc, current) => acc + current, 0); // 10
*/
 

/**
* @name array.reduceRight(callbackFn, initialValue)
* @description Ejecuta una función reductora sobre cada elemento del array, de derecha a izquierda, a fin de reducirlo a un único valor.
* @param {function(accumulator, currentValue, index, array): any} callbackFn - Función reductora.
* @param {*} [initialValue] - Valor inicial del `accumulator`.
* @returns {any} - El valor final resultante de la reducción.
*
* @example
* const numbers = [1, 2, 3, 4];
* const sumRight = numbers.reduceRight((acc, current) => acc + current, 0); // 10
*/