@bemoje/array 1.0.0 → 1.0.2

package/index.d.ts

@@ -0,0 +1,368 @@
+/**
+ * Calculates the average of an array of numbers.
+ * @returns The average of all numbers in the array.
+ * @throws an error if the input array is empty.
+ * @param array The array of numbers.
+ * @example ```ts
+ * const numbers = [1, 2, 3, 4, 5];
+ * arrAverage(numbers);
+ * //=> 3
+ * ```
+ */
+declare function arrAverage(array: number[]): number;
+
+/**
+ * Coerce each element of an array to string.
+ * @template T - The type of elements in the input array.
+ * @returns A new array where each element is the string representation of the corresponding element in the input array.
+ * @param array The array to iterate over.
+ * @example ```ts
+ * const numbers = [1, 2, 3];
+ * arrEachToString(numbers);
+ * //=> ['1', '2', '3']
+ * ```
+ */
+declare function arrEachToString<T>(array: T[]): string[];
+
+/**
+ * Returns an array of indices where the predicate function returns true for the corresponding element in the input array.
+ * @param input - The array to search.
+ * @param predicate - The function to test each element of the array.
+ * @returns An array of indices where the predicate function returns true.
+ */
+declare function arrFindIndicesOf<T>(input: Array<T>, predicate: (value: T) => boolean): number[];
+
+/**
+ * Get array element at index or create it using factory function if it doesn't exist.
+ */
+declare function arrGetOrDefault<V>(array: V[], index: number, factory: (index: number) => V): V;
+
+/**
+ * Checks if an array has any duplicate elements.
+ * @param arr - The array to check for duplicates.
+ * @returns A boolean indicating whether the array has duplicates.
+ * @typeParam T - The type of elements in the array.
+ */
+declare function arrHasDuplicates<T>(arr: T[]): boolean;
+
+/**
+ * Returns all indexes at which an element is found.
+ * @param input The array to search
+ * @template T - The type of elements in the input array.
+ * @returns An array of indices where the specified element can be found.
+ * @param element The element to find
+ * @example ```ts
+ *  const inputArray = [1, 2, 3, 2, 4, 2, 5];
+ *  const elementToFind = 2;
+ *  arrIndicesOf(inputArray, elementToFind);
+ *  //=> [1, 3, 5]
+ *  ```
+ */
+declare function arrIndicesOf<T>(input: Array<T>, element: T): number[];
+
+/**
+ * Returns the last element of an array.
+ * Throws an error if the array is empty.
+ * @template T The type of elements in the array.
+ * @param array The array to get the last element from.
+ * @returns The last element of the array.
+ * @throws If the array is empty.
+ * @example const numbers = [1, 2, 3, 4, 5];
+ * const lastNumber = arrLast(numbers);
+ * //=> 5
+ */
+declare function arrLast<T>(array: T[]): T;
+
+/**
+ * This function takes an array and a callback function as arguments. It applies the callback function to each element of the array, mutating the original array in the process.
+ * @template T The type of elements in the input array.
+ * @param input The array to be mapped over.
+ * @param f The callback function to be applied to each element of the array. This function takes three arguments: the current element, its index, and the original array.
+ * @returns The original array, mutated by the callback function.
+ * @example ```ts
+ * arrMapMutable([1, 2, 3], (value: number) => value * 2);
+ * //=> [2, 4, 6]
+ * ```
+ */
+declare function arrMapMutable<T>(input: Array<T>, f: (value: T, index: number, array: T[]) => T): Array<T>;
+
+/**
+ * Convert an array of objects to a two-dimensional table.
+ * @param objects The array of objects to convert to a table.
+ * @template T - The type of the values in the objects.
+ * @param options.headers An optional array of strings specifying the headers (property names) to use. If not provided, the function will use all unique keys found in the objects.
+ * @param options.emptyCell An optional value to use for empty cells. If not provided, the function will use `undefined`.
+ * @returns A 2D array (table) where each row represents an object and each column represents a property of the object.
+ * @param options The options for converting the objects to a table.
+ * @example ```ts
+ * arrObjectsToTable(
+ *   [
+ *     { a: 1, b: 2 },
+ *     { a: 3, b: 4, c: 5 },
+ *   ],
+ *   { emptyCell:1 },
+ * ) //=> [ [ 'a', 'b', 'c' ], [ 1, 2,1 ], [ 3, 4, 5 ] ]
+ * ```
+ */
+declare function arrObjectsToTable<T, E>(
+  objects: Record<string, T | undefined>[],
+  options?: {
+    headers?: string[];
+    emptyCell?: E;
+  },
+): Array<Array<string | T | E>>;
+
+/**
+ * Returns an array of all unique object keys found in an array of objects.
+ * @template T - The type of values in the input objects.
+ * @returns An array of unique keys present in the input objects.
+ * @param objects The array of objects.
+ * @example ```ts
+ * const objects = [
+ *   { name: 'John', age: 25 },
+ *   { name: 'Jane', gender: 'female' },
+ *   { name: 'Bob', age: 30, gender: 'male' },
+ * ];
+ * arrObjectsUniqueKeys(objects);
+ * //=> ['name', 'age', 'gender']
+ * ```
+ */
+declare function arrObjectsUniqueKeys<T>(objects: Record<string, T>[]): string[];
+
+/**
+ * Remove a given element from a copy of a given array and return the resulting array.
+ */
+declare function arrRemove<T>(arr: T[], elementToRemove: T): T[];
+
+/**
+ * Remove duplicates from an array
+ * @remarks This function uses the JavaScript Set object to remove duplicate values from an array.
+ * @typeparam T - The type of elements in the array.
+ * @returns The new array with duplicates removed.
+ * @param array The array from which to remove duplicates.
+ * @example ```ts
+ * const array = [1, 2, 2, 3, 4, 4, 5];
+ * arrRemoveDuplicates(array);
+ * //=> [1, 2, 3, 4, 5]
+ * ```
+ */
+declare function arrRemoveDuplicates<T>(array: T[]): T[];
+
+/**
+ * Remove elements in-place from an array.
+ */
+declare function arrRemoveMutable<T>(arr: T[], elementToRemove: T): void;
+
+/**
+ * Shuffle items in an array in-place. Guarantees changes.
+ * @remarks This function does not guarantee that the order of the elements will be different after shuffling.
+ * @typeparam T - The type of the elements in the input array.
+ * @returns The same array, but shuffled.
+ * @param input The array to shuffle.
+ * @example ```ts
+ * const input = [1, 2, 3, 4, 5];
+ * arrShuffle(input);
+ * //=> [3, 1, 5, 2, 4]
+ * ```
+ */
+declare function arrShuffle<T>(input: Array<T>): Array<T>;
+
+/**
+ * Sorts an array of numbers, bigints, or booleans in ascending order.
+ * @returns The sorted array.
+ * @remarks This function uses the JavaScript `Array.prototype.sort()` method, which sorts elements in place.
+ * Therefore, the original array will be modified.
+ * @throws If any element in the input array is not a number, bigint, or boolean.
+ * @param input The array to be sorted.
+ * @example ```ts
+ * const input = [5, 2n, true, 10, false];
+ * arrSortNumeric(input);
+ * //=> [false, true, 2n, 5, 10]
+ * ```
+ */
+declare function arrSortNumeric(input: Array<number | bigint | boolean>): Array<number | bigint | boolean>;
+
+/**
+ * Returns an index in the sorted array where the specified value could be inserted while maintaining the sorted order of the array.
+ * If the element is already in the array, returns the index after the last instance of the element.
+ * @param array - The sorted array to search.
+ * @param value - The value to locate in the array.
+ * @param comparator - A function that defines the sort order. If omitted, the array elements are converted to strings, then sorted according to each character's Unicode code point value.
+ * @returns The index at which the value could be inserted into array to maintain the array's sorted order.
+ * @example ```ts
+ * const array = [1, 2, 3, 5, 6];
+ * const value = 4;
+ * const comparator = (a, b) => a - b;
+ * const index = arrSortedLowerBound(array, value, comparator);
+ * console.log(index); // Output: 3
+ * ```
+ */
+declare function arrSortedInsertionIndex<T>(
+  array: readonly T[],
+  value: T,
+  comparator: (a: T, b: T) => number,
+): number;
+
+/**
+ * Calculates the sum of an array of numbers.
+ * @returns The sum of all numbers in the array.
+ * @param array The array of numbers to sum.
+ * @example ```ts
+ * const numbers = [1, 2, 3, 4, 5];
+ * arrSum(numbers);
+ * //=> 15
+ * ```
+ */
+declare function arrSum(array: number[]): number;
+
+/**
+ * Swaps two elements in an array. This function takes an input array and swaps the elements at the specified indices.
+ * @param to The index of the element to swap to.
+ * @param from The index of the element to swap from.
+ * @template T - The type of elements in the array.
+ * @returns The modified array with swapped elements.
+ * @throws Will throw an error if 'from' or 'to' is not a valid index in the array.
+ * @param input The input array.
+ * @example ```ts
+ * const arr = [1, 2, 3, 4, 5]
+ * arrSwap(arr, 1, 3) //=> [1, 4, 3, 2, 5]
+ * ```
+ */
+declare function arrSwap<T>(input: Array<T>, from: number, to: number): Array<T>;
+
+/**
+ * Asserts that all rows in a 2D array have the same length.
+ * @param - Optional array of headers to compare the row length against.
+ * @throws If any row in the array has a different length than the others.
+ * @param headers Optional. An array of headers. If provided, each row must have the same length as this array.
+ * @typeparam T - The type of elements in the rows.
+ * @param rows The 2D array to check.
+ * @example ```ts
+ *  const rows = [
+ *    [1, 2, 3],
+ *    [4, 5, 6],
+ *    [7, 8, 9],
+ *  ];
+ *  arrTableAssertRowsSameLength(rows);
+ *  //=> undefined
+ *  const rowsWithDifferentLength = [
+ *    [1, 2, 3],
+ *    [4, 5],
+ *    [7, 8, 9],
+ *  ];
+ *  arrTableAssertRowsSameLength(rowsWithDifferentLength);
+ *  //=> Error: Expected 3 columns, got 2
+ *  ```
+ */
+declare function arrTableAssertRowsSameLength<T>(rows: T[][], headers?: string[]): void;
+
+/**
+ * Coerce each value of a 2D array table to string.
+ * @template T - The type of the elements in the input array.
+ * @returns The converted 2D array where each element is a string.
+ * @param table The 2D array to convert.
+ * @example ```ts
+ * const input: number[][] = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
+ * arrTableEachToString(input);
+ * //=> [['1', '2', '3'], ['4', '5', '6'], ['7', '8', '9']]
+ * ```
+ */
+declare function arrTableEachToString<T>(table: T[][]): string[][];
+
+/**
+ * Generator that iterates through a 2D array table, yielding objects with header keys and row values.
+ */
+declare function arrTableIterateAsObjects<T>(
+  rows: T[][],
+  headers: string[],
+  ignoreHeaders?: Set<string>,
+): Generator<Record<string, T>, void, unknown>;
+
+/**
+ * Removes specified columns from a 2D array table.
+ * @param table - The 2D array (table) from which columns will be removed. The first row of the table is assumed to contain column names.
+ * @param removeColumnNames - The names of the columns to be removed. These should match the entries in the first row of the table.
+ * @returns A new 2D array (table) with the specified columns removed.
+ */
+declare function arrTableRemoveColumns(table: string[][], ...removeColumnNames: string[]): string[][];
+
+/**
+ * Converts a 2D array to a CSV string.
+ * @param input The input 2D array.
+ * @remarks This function is useful for exporting data to CSV format.
+ * @param replaceLinebreakWith The character used to replace line breaks in the CSV string. Defaults to '|'.
+ * @typeparam T - The type of the elements in the input array.
+ * @returns The CSV string representation of the input array.
+ * @param delimiter The delimiter to use for separating values in the CSV string.
+ * @example ```ts
+ * const input = [
+ *   ['Name', 'Age', 'Country'],
+ *   ['John', '25', 'USA'],
+ *   ['Alice', '30', 'Canada'],
+ *   ['Bob', '35', 'UK'],
+ * ];
+ * arrTableToCsv(input);
+ * //=> "Name;Age;Country\nJohn;25;USA\nAlice;30;Canada\nBob;35;UK"
+ * ```
+ */
+declare function arrTableToCsv<T>(input: T[][], delimiter?: string, replaceLinebreakWith?: string): string;
+
+/**
+ * Converts a 2D array representing a table into an array of objects.
+ * @param rows The 2D array representing the table.
+ * @template T - The type of the elements in the rows.
+ * @param headers The headers to use as keys for the objects. If not provided, the first row of the table is used as headers.
+ * @returns An array of objects, where each object represents a row in the table.
+ * @throws Throws an error if the headers are not provided and the table is empty or only contains one row.
+ * @param headers Optional array of headers for the table.
+ * @example ```ts
+ * const table = [
+ *   ['Name', 'Age', 'Country'],
+ *   ['John', 25, 'USA'],
+ *   ['Jane', 30, 'Canada'],
+ * ];
+ * const headers = ['Name', 'Age', 'Country'];
+ * arrTableToObjects(table, headers) //=> [
+ * //   { Name: 'John', Age: 25, Country: 'USA' },
+ * //   { Name: 'Jane', Age: 30, Country: 'Canada' },
+ * // ]
+ * ```
+ */
+declare function arrTableToObjects<T>(
+  rows: T[][],
+  headers?: string[],
+  ignoreKeys?: Set<string>,
+): Record<string, T>[];
+
+/**
+ * Short and condensed string representation of an array, easy to read for error outputs or similar.
+ */
+declare function arrayToString<T>(array: T[]): string;
+
+export {
+  arrAverage,
+  arrEachToString,
+  arrFindIndicesOf,
+  arrGetOrDefault,
+  arrHasDuplicates,
+  arrIndicesOf,
+  arrLast,
+  arrMapMutable,
+  arrObjectsToTable,
+  arrObjectsUniqueKeys,
+  arrRemove,
+  arrRemoveDuplicates,
+  arrRemoveMutable,
+  arrShuffle,
+  arrSortNumeric,
+  arrSortedInsertionIndex,
+  arrSum,
+  arrSwap,
+  arrTableAssertRowsSameLength,
+  arrTableEachToString,
+  arrTableIterateAsObjects,
+  arrTableRemoveColumns,
+  arrTableToCsv,
+  arrTableToObjects,
+  arrayToString,
+};