@nevware21/ts-utils
Version:
Comprehensive TypeScript/JavaScript utility library with cross-environment support (Node.js, browser, web worker) providing helper functions, polyfills (ES5-ES2023), type checking utilities, and optimized implementations for better minification and code r
1,077 lines (1,049 loc) • 421 kB
TypeScript
/// <reference lib="es2015" />
/**
* Appends the `elms` to the `target` where the elms may be an array, a single object
* or an iterator object
* @group Array
* @group Iterator
* @example
* ```ts
* let theArray = arrAppend([], 1);
* arrAppend(theArray, [ 2, 3, 4 ]);
* arrAppend(theArray, [ "a", "b", "c" ]);
* // theArray is now [ 1, 2, 3, 4, "a", "b", "c" ]
* ```
* @param target - The target array
* @param elms - The item, array of items an iterable or iterator object of items to add to the target
* @returns The passed in target array
* @example
* ```ts
* // Adding a single value
* arrAppend([], undefined); // []
* arrAppend([], 0); // [ 0 ]
* arrAppend([1], undefined); // [ 1 ]
* arrAppend([1], 2); // [ 1, 2 ]
*
* // Adding an array
* arrAppend([], [] as number[]); // []
* arrAppend([], [0]); // [ 0 ]
* arrAppend([1], []); // [ 1 ]
* arrAppend([1], [2]); // [ 1, 2 ]
*
* // Adding with an iterator
* arrAppend([], ([] as number[]).values()); // []
* arrAppend([], [0].values()); // [ 0 ]
* arrAppend([1], [].keys()); // [ 1 ]
* arrAppend([1], [2].values()); // [ 1, 2 ]
* arrAppend([1], [2].keys()); // [ 1, 0 ] - 0 is from the index from the first element
* ```
*/
export declare function arrAppend<T>(target: T[], elms: T | T[] | Iterator<T>): T[];
/**
* The arrAt() method takes an integer value and returns the item at that index, allowing for
* positive and negative integers. Negative integers count back from the last item in the array.
* This is an ES2022 feature with polyfill support for older environments.
* @function
* @since 0.14.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the type of array elements
* @param theArray - The array or array-like object to get element from
* @param index - The index of the element to return. Negative index counts from the end
* @returns The element at the specified index, or undefined if index is out of range
* @example
* ```ts
* arrAt([1, 2, 3, 4, 5], 0); // 1
* arrAt([1, 2, 3, 4, 5], 2); // 3
* arrAt([1, 2, 3, 4, 5], -1); // 5
* arrAt([1, 2, 3, 4, 5], -2); // 4
* arrAt([1, 2, 3], 10); // undefined
* arrAt([1, 2, 3], -10); // undefined
*
* // Array-like objects
* arrAt({ length: 3, 0: "a", 1: "b", 2: "c" }, -1); // "c"
* ```
*/
export declare const arrAt: <T>(theArray: ArrayLike<T>, index: number) => T;
/**
* Deep copy handler to identify and copy arrays.
* @since 0.4.4
* @group Object - Deep Copy
* @param details - The details object for the current property being copied
* @returns `true` if the current value is a function otherwise `false`
*/
export declare function arrayDeepCopyHandler(details: IObjDeepCopyHandlerDetails): boolean;
/**
* The arrChunk() method returns a new array with elements divided into groups of a specified size.
* The last group may have fewer elements if the array length is not divisible by the chunk size.
* @function
* @since 0.14.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the base type of array elements
* @param theArray - The array or array-like object to chunk
* @param size - The size of each chunk. Must be a positive integer
* @returns A new array of chunks, where each chunk is an array of the specified size
* @example
* ```ts
* arrChunk([1, 2, 3, 4, 5, 6, 7], 2); // [[1, 2], [3, 4], [5, 6], [7]]
* arrChunk([1, 2, 3, 4, 5], 3); // [[1, 2, 3], [4, 5]]
* arrChunk([1, 2, 3], 1); // [[1], [2], [3]]
* arrChunk([1, 2, 3], 5); // [[1, 2, 3]]
* arrChunk([], 2); // []
*
* // Array-like objects
* arrChunk({ length: 5, 0: "a", 1: "b", 2: "c", 3: "d", 4: "e" }, 2);
* // [["a", "b"], ["c", "d"], ["e"]]
* ```
*/
export declare function arrChunk<T>(theArray: ArrayLike<T> | null | undefined, size: number): T[][];
/**
* The arrCompact() method returns a new array with all falsy values removed.
* Falsy values include: false, 0, -0, 0n, "", null, undefined, and NaN.
* @function
* @since 0.14.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the base type of array elements
* @param theArray - The array or array-like object to compact
* @returns A new array with all falsy values filtered out
* @example
* ```ts
* arrCompact([0, 1, false, 2, "", 3, null, undefined, 4]); // [1, 2, 3, 4]
* arrCompact([false, 0, "", null, undefined]); // []
* arrCompact([1, 2, 3]); // [1, 2, 3]
* arrCompact([]); // []
*
* // Array-like objects
* arrCompact({ length: 5, 0: 0, 1: 1, 2: false, 3: 2, 4: null }); // [1, 2]
* ```
*/
export declare function arrCompact<T>(theArray: ArrayLike<T | null | undefined | false | 0 | ""> | null | undefined): T[];
/**
* The arrContains() method determines whether an array contains a certain value among its
* entries, returning true or false as appropriate.
* @function
* @since 0.8.0
* @group Array
* @group ArrayLike
* @param theArray - The array or array like object of elements to be searched.
* @param searchElement - The value to search for
* @param fromIndex - The optional Zero-based index at which to start searching, converted to an integer.
* - Negative index counts back from the end of the array — if fromIndex \< 0, fromIndex + array.length
* is used. However, the array is still searched from front to back in this case.
* - If fromIndex \< -array.length or fromIndex is omitted, 0 is used, causing the entire array to be searched.
* - If fromIndex \>= array.length, the array is not searched and false is returned.
* @returns A boolean value which is true if the value searchElement is found within the array (or the part of
* the array indicated by the index fromIndex, if specified).
* @example
* ```ts
* arrContains([1, 2, 3], 2); // true
* arrContains([1, 2, 3], 4); // false
* arrContains([1, 2, 3], 3, 3); // false
* arrContains([1, 2, 3], 3, -1); // true
* arrContains([1, 2, NaN], NaN); // true
* arrContains(["1", "2", "3"], 3 as any); // false
*
* // Array Like
* arrContains({ length: 3, 0: 1, 1: 2, 2: 3 }, 2); // true
* arrContains({ length: 3, 0: 1, 1: 2, 2: 3 }, 4); // false
* arrContains({ length: 3, 0: 1, 1: 2, 2: 3 }, 3, 3); // false
* arrContains({ length: 3, 0: 1, 1: 2, 2: 3 }, 3, -1); // true
* arrContains({ length: 3, 0: 1, 1: 2, 2: NaN }, NaN); // true
* arrContains({ length: 3, 0: "1", 1: "2", 2: "3" }, 3 as any); // false
* ```
*/
export declare const arrContains: <T>(theArray: ArrayLike<T>, searchElement: T, fromIndex?: number) => boolean;
/**
* The arrDifference() method returns a new array containing elements from the first array
* that do not exist in any of the other provided arrays. Uses strict equality (===) for comparison.
* @since 0.14.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the base type of array elements
* @param theArray - The source array to compare from
* @param excludeArrays - One or more arrays whose values should be excluded
* @returns A new array containing elements only in the source array
* @example
* ```ts
* arrDifference([1, 2, 3, 4], [2, 4]); // [1, 3]
* arrDifference([1, 2, 3], [2], [3]); // [1]
* arrDifference(["a", "b", "c"], ["b"]); // ["a", "c"]
* arrDifference([1, 2, 3], []); // [1, 2, 3]
* arrDifference([], [1, 2]); // []
*
* // Array-like objects
* arrDifference({ length: 3, 0: 1, 1: 2, 2: 3 }, [2]); // [1, 3]
* ```
*/
export declare function arrDifference<T>(theArray: ArrayLike<T> | null | undefined, ...excludeArrays: ArrayLike<T>[]): T[];
/**
* The arrDrop() method returns a new array with the first n elements removed from the source array.
* If n is greater than the array length, returns empty array. If n is negative or 0, returns all elements.
* @since 0.14.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the base type of array elements
* @param theArray - The array or array-like object to drop from
* @param count - The number of elements to drop from the beginning
* @returns A new array with the first n elements removed
* @example
* ```ts
* arrDrop([1, 2, 3, 4, 5], 2); // [3, 4, 5]
* arrDrop(["a", "b", "c"], 1); // ["b", "c"]
* arrDrop([1, 2], 5); // []
* arrDrop([1, 2, 3], 0); // [1, 2, 3]
* arrDrop([1, 2, 3], -1); // [1, 2, 3]
*
* // Array-like objects
* arrDrop({ length: 4, 0: 1, 1: 2, 2: 3, 3: 4 }, 2); // [3, 4]
* ```
*/
export declare function arrDrop<T>(theArray: ArrayLike<T> | null | undefined, count: number): T[];
/**
* The arrDropWhile() method returns a new array with elements from the beginning removed
* as long as the predicate function returns true. Once the predicate returns false,
* all remaining elements (including that one) are included in the result.
* @since 0.14.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the base type of array elements
* @typeParam E - Identifies the narrowed type when using type guards
* @param theArray - The array or array-like object to drop from
* @param callbackFn - Function to test each element. Return true to drop, false to stop dropping
* @param thisArg - Optional value to use as `this` when executing callbackFn
* @returns A new array with leading elements removed while predicate was true
* @example
* ```ts
* arrDropWhile([1, 2, 3, 4, 1], x => x < 3); // [3, 4, 1]
* arrDropWhile([2, 4, 6, 1, 8], x => x % 2 === 0); // [1, 8]
* arrDropWhile([1, 2, 3], x => x > 5); // [1, 2, 3]
* arrDropWhile([1, 2, 3], x => x < 5); // []
*
* // Array-like objects
* arrDropWhile({ length: 4, 0: 1, 1: 2, 2: 3, 3: 4 }, x => x < 3); // [3, 4]
* ```
*/
export declare function arrDropWhile<T, E extends T = T>(theArray: ArrayLike<T> | null | undefined, callbackFn: ArrPredicateCallbackFn<T, E> | ArrPredicateCallbackFn2<T>, thisArg?: any): T[];
/**
* The arrEvery() method is an iterative method. It calls a provided callbackFn function once for
* each element in an array, until the callbackFn returns a falsy value. If such an element is found,
* arrEvery() immediately returns false and stops iterating through the array. Otherwise, if callbackFn
* returns a truthy value for all elements, every() returns true.
* @function
* @since 0.8.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the base type of array elements
* @typeParam E - Identifies a more specific instance of the base array type
* @param theArray - The array or array like object of elements to be searched.
* @param callbackFn - A function that accepts up to three arguments of type {@link ArrPredicateCallbackFn} or
* {@link ArrPredicateCallbackFn2}. The predicate function is called for each element in the thArray until
* the predicate returns a value which is coercible to the Boolean value false, or until the end of the array.
* @param thisArg - A value to use as this when executing callbackFn. Defaults to the array if not provided.
* @return `true` if the callbackFn returns a `truthy` value for every array elements. Otherwise `false`.
* @example
* ```ts
* function isBigEnough<T>(element: T, index: number, array: T[]) {
* return element >= 10;
* }
*
* arrEvery([12, 5, 8, 130, 44], isBigEnough); // false
* arrEvery([12, 54, 18, 130, 44], isBigEnough); // true
*
* const isSubset = <T>(array1: T[], array2: T[]) => arrEvery(array2, (element) => arrIncludes(array1, element));
*
* isSubset([1, 2, 3, 4, 5, 6, 7], [5, 7, 6]); // true
* isSubset([1, 2, 3, 4, 5, 6, 7], [5, 8, 7]); // false
*
* arrEvery([1, , 3], (x) => x !== undefined); // true
* arrEvery([2, , 2], (x) => x === 2); // true
*
* // Array Like combinations
* isSubset([1, 2, 3, 4, 5, 6, 7], { length: 3, 0: 5, 1: 7, 2: 6}); // true
* isSubset([1, 2, 3, 4, 5, 6, 7], { length: 3, 0: 5, 1: 8, 2: 7}); // false
*
* isSubset({ length: 7, 0: 1, 1: 2, 2: 3, 3: 4, 4: 5, 5: 6, 6: 7 }, [ 5, 7, 6 ]); // true
* isSubset({ length: 7, 0: 1, 1: 2, 2: 3, 3: 4, 4: 5, 5: 6, 6: 7 }, [5, 8, 7]); // false
*
* isSubset({ length: 7, 0: 1, 1: 2, 2: 3, 3: 4, 4: 5, 5: 6, 6: 7 }, { length: 3, 0: 5, 1: 7, 2: 6}); // true
* isSubset({ length: 7, 0: 1, 1: 2, 2: 3, 3: 4, 4: 5, 5: 6, 6: 7 }, { length: 3, 0: 5, 1: 8, 2: 7}); // false
* ```
*/
export declare const arrEvery: <T, E extends T>(theArray: ArrayLike<T>, callbackFn: ArrPredicateCallbackFn<T, E> | ArrPredicateCallbackFn2<T>, thisArg?: any) => theArray is T[];
/**
* The arrFill() method changes all elements in an array to a static value, from a start index
* (default 0) to an end index (default array.length). It returns the modified array.
* This method mutates the array.
* @function
* @since 0.14.0
* @group Array
* @typeParam T - Identifies the type of array elements
* @param theArray - The array to fill
* @param value - Value to fill the array with
* @param start - Start index (inclusive), defaults to 0. Negative index counts from the end
* @param end - End index (exclusive), defaults to array.length. Negative index counts from the end
* @returns The modified array
* @example
* ```ts
* arrFill([1, 2, 3], 0); // [0, 0, 0]
* arrFill([1, 2, 3], 4, 1); // [1, 4, 4]
* arrFill([1, 2, 3], 5, 1, 2); // [1, 5, 3]
* arrFill([1, 2, 3], 6, -2); // [1, 6, 6]
* arrFill([1, 2, 3], 7, -3, -1); // [7, 7, 3]
* arrFill([], 1); // []
* ```
*/
export declare const arrFill: <T>(theArray: WritableArrayLike<T>, value: T, start?: number, end?: number) => WritableArrayLike<T>;
/**
* The arrFilter() method creates a shallow copy of a portion of a given array, filtered down to just the elements
* from the given array that pass the test implemented by the provided function.
*
* The filter() method is an iterative method. It calls a provided callbackFn function once for each element in an
* array, and constructs a new array of all the values for which callbackFn returns a truthy value. Array elements
* which do not pass the callbackFn test are not included in the new array.
*
* `callbackFn` is invoked only for array indexes which have assigned values. It is not invoked for empty slots in
* sparse arrays.
*
* The arrFilter() method is a copying method. It does not alter this but instead returns a shallow copy that contains
* the same elements as the ones from the original array (with some filtered out). However, the function provided as
* callbackFn can mutate the array. Note, however, that the length of the array is saved before the first invocation
* of callbackFn. Therefore:
* - `callbackFn` will not visit any elements added beyond the array's initial length when the call to arrFilter()
* began.
* - Changes to already-visited indexes do not cause callbackFn to be invoked on them again.
* - If an existing, yet-unvisited element of the array is changed by callbackFn, its value passed to the `callbackFn`
* will be the value at the time that element gets visited. Deleted elements are not visited.
* @function
* @since 0.8.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the base type of the elements.
* @typeParam E - Identifies a more specific instance of the base array type.
* @param theArray - The array or array like object of elements to be searched.
* @param callbackFn - A function that accepts up to three arguments of type {@link ArrPredicateCallbackFn} or
* {@link ArrPredicateCallbackFn2}. The predicate function is called for each element in the thArray until
* the predicate returns a value which is coercible to the Boolean value false, or until the end of the array.
* @param thisArg - A value to use as this when executing callbackFn. Defaults to the array if not provided.
* @return A shallow copy of a portion of the given array, filtered down to just the elements from the given
* array that pass the test implemented by the provided function. If no elements pass the test, an empty array
* will be returned.
* @example
* ```ts
* function isBigEnough<T>(value: T) {
* return value >= 10;
* }
*
* const filtered = arrFilter([12, 5, 8, 130, 44], isBigEnough);
* // filtered is [12, 130, 44]
*
* const arrayLikeFiltered = arrFilter({ length: 5, 0: 12, 1: 5, 2: 8, 3: 130, 4: 44}, isBigEnough);
* // arrayLikeFiltered is [12, 130, 44]
*
* const array = [-3, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
*
* function isPrime(num) {
* for (let i = 2; num > i; i++) {
* if (num % i === 0) {
* return false;
* }
* }
* return num > 1;
* }
*
* console.log(arrFilter(array, isPrime)); // [2, 3, 5, 7, 11, 13]
* ```
*/
export declare const arrFilter: <T, E extends T>(theArray: ArrayLike<T>, callbackFn: ArrPredicateCallbackFn<T, E> | ArrPredicateCallbackFn2<T>, thisArg?: any) => T[] | E[];
/**
* The arrFind() method returns the first element in the provided array that satisfies
* the provided testing function. If no values satisfy the testing function, undefined
* is returned.
* - If you need the index of the found element in the array, use {@link arrFindIndex}.
* - If you need to find the index of a value, use arrIndexOf(). (It's similar to {@link arrFindIndex}, but
* checks each element for equality with the value instead of using a testing function.)
* - If you need to find if a value exists in an array, use {@link arrIncludes}. Again, it checks each element for
* equality with the value instead of using a testing function.
* - If you need to find if any element satisfies the provided testing function, use {@link arrSome}.
*
* The arrFind() method is an iterative method. It calls a provided `callbackFn` function once for each element
* in an array in ascending-index order, until `callbackFn` returns a truthy value. arrFind() then returns that
* element and stops iterating through the array. If callbackFn never returns a truthy value, arrFind() returns
* undefined.
*
* `callbackFn` is invoked for every index of the array, not just those with assigned values. Empty slots in
* sparse arrays behave the same as undefined.
*
* arrFind() does not mutate the array on which it is called, but the function provided as callbackFn can.
* Note, however, that the length of the array is saved before the first invocation of `callbackFn`. Therefore:
* - `callbackFn` will not visit any elements added beyond the array's initial length when the call to arrFind() began.
* - Changes to already-visited indexes do not cause callbackFn to be invoked on them again.
* - If an existing, yet-unvisited element of the array is changed by callbackFn, its value passed to the
* `callbackFn` will be the value at the time that element gets visited. Deleted elements are visited as if they
* were undefined.
* @function
* @since 0.8.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the base type of array elements
* @typeParam E - Identifies a more specific instance of the base array type
* @param theArray - The array or array like object of elements to be searched.
* @param callbackFn - A function that accepts up to three arguments of type {@link ArrPredicateCallbackFn} or
* {@link ArrPredicateCallbackFn2}. The predicate function is called for each element in the thArray until
* the predicate returns a value which is coercible to the Boolean value false, or until the end of the array.
* @param thisArg - A value to use as this when executing callbackFn. Defaults to the array if not provided.
* @return The first element in the array that satisfies the provided testing function. Otherwise, undefined
* is returned.
* @example
* ```ts
* const inventory = [
* { name: "apples", quantity: 2 },
* { name: "bananas", quantity: 0 },
* { name: "cherries", quantity: 5 },
* ];
*
* function isCherries(fruit) {
* return fruit.name === "cherries";
* }
*
* console.log(arrFind(inventory, isCherries));
* // { name: 'cherries', quantity: 5 }
*
* function isPrime(element, index, array) {
* let start = 2;
* while (start <= Math.sqrt(element)) {
* if (element % start++ < 1) {
* return false;
* }
* }
* return element > 1;
* }
*
* console.log(arrFind([4, 6, 8, 12], isPrime)); // undefined, not found
* console.log(arrFind([4, 5, 8, 12], isPrime)); // 5
*
* // Array Like
* console.log(arrFind({ length: 4, 0: 4, 1: 6, 2: 8, 3: 12 }, isPrime)); // undefined, not found
* console.log(arrFind({ length: 4:, 0: 4, 1: 5, 2: 8, 3: 12 }, isPrime)); // 5
* ```
*/
export declare const arrFind: <T, E extends T>(theArray: ArrayLike<T>, callbackFn: ArrPredicateCallbackFn<T, E> | ArrPredicateCallbackFn2<T>, thisArg?: any) => T | E;
/**
* The arrFindIndex() method returns the index of the first element in an array that satisfies the provided testing
* function. If no elements satisfy the testing function, -1 is returned.
*
* The arrFindIndex() is an iterative method. It calls a provided callbackFn function once for each element in an
* array in ascending-index order, until callbackFn returns a truthy value. arrFindIndex() then returns the index
* of that element and stops iterating through the array. If `callbackFn` never returns a truthy value, arrFindIndex()
* returns -1.
*
* `callbackFn` is invoked for every index of the array, not just those with assigned values. Empty slots in sparse
* arrays behave the same as undefined.
*
* arrFindIndex() does not mutate the array on which it is called, but the function provided as `callbackFn` can.
* Note, however, that the length of the array is saved before the first invocation of callbackFn. Therefore:
* - `callbackFn` will not visit any elements added beyond the array's initial length when the call to arrFindIndex() began.
* - Changes to already-visited indexes do not cause `callbackFn` to be invoked on them again.
* If an existing, yet-unvisited element of the array is changed by `callbackFn`, its value passed to the `callbackFn`
* will be the value at the time that element gets visited. Deleted elements are visited as if they were undefined.
* @function
* @since 0.8.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the base type of array elements
* @typeParam E - Identifies a more specific instance of the base array type
* @param theArray - The array or array like object of elements to be searched.
* @param callbackFn - A function that accepts up to three arguments of type {@link ArrPredicateCallbackFn} or
* {@link ArrPredicateCallbackFn2}. The predicate function is called for each element in the thArray until
* the predicate returns a value which is coercible to the Boolean value false, or until the end of the array.
* @param thisArg - A value to use as this when executing callbackFn. Defaults to the array if not provided.
* @return The index of the first element in the array that passes the test. Otherwise, -1.
* @example
* ```ts
* const inventory: Array<{ name: string, quantity: number}> = [
* { name: "apples", quantity: 2 },
* { name: "bananas", quantity: 0 },
* { name: "cherries", quantity: 5 }
* ];
*
* function isCherries(fruit: { name: string, quantity: number}) {
* return fruit.name === "cherries";
* }
*
* arrFindIndex(inventory, isCherries); // 2
*
* function isPrime(element: number) {
* if (element % 2 === 0 || element < 2) {
* return false;
* }
*
* for (let factor = 3; factor <= Math.sqrt(element); factor += 2) {
* if (element % factor === 0) {
* return false;
* }
* }
* return true;
* }
*
* arrFindIndex([4, 6, 8, 9, 12], isPrime) // -1
* arrFindIndex([4, 6, 7, 9, 12], isPrime) // 2
*
* // Array Like
* arrFindIndex({ length: 5, 0: 4, 1: 6, 2: 8, 3: 9, 4: 12 }, isPrime) // -1
* arrFindIndex({ length: 5:, 0: 4, 1: 6, 2: 7, 3: 9, 4: 12 }, isPrime) // 2
* ```
*/
export declare const arrFindIndex: <T, E extends T>(theArray: ArrayLike<T>, callbackFn: ArrPredicateCallbackFn<T, E> | ArrPredicateCallbackFn2<T>, thisArg?: any) => number;
/**
* The arrFindLast() method iterates the array in reverse order and returns the value of the first element that
* satisfies the provided testing function. If no elements satisfy the testing function, undefined is returned.
* - If you need the index of the found element in the array, use arrFindLastIndex().
* - If you need to find the index of a value, use arrLastIndexOf(). (It's similar to arrFindLastIndex(), but checks
* each element for equality with the value instead of using a testing function.)
* - If you need to find if a value exists in an array, use {@link arrIncludes}. Again, it checks each element for
* equality with the value instead of using a testing function.
* - If you need to find if any element satisfies the provided testing function, use {@link arrSome}.
*
* The arrFindLast() method is an iterative method. It calls a provided callbackFn function once for each element
* in an array in descending-index order, until callbackFn returns a truthy value. arrFindLast() then returns that
* element and stops iterating through the array. If `callbackFn` never returns a truthy value, arrFindLast() returns
* undefined.
*
* `callbackFn` is invoked for every index of the array, not just those with assigned values. Empty slots in sparse
* arrays behave the same as undefined.
*
* arrFindLast() does not mutate the array on which it is called, but the function provided as `callbackFn` can.
* Note, however, that the length of the array is saved before the first invocation of `callbackFn`. Therefore:
* - `callbackFn` will not visit any elements added beyond the array's initial length when the call to arrFindLast() began.
* - Changes to already-visited indexes do not cause callbackFn to be invoked on them again.
* - If an existing, yet-unvisited element of the array is changed by `callbackFn`, its value passed to the `callbackFn`
* will be the value at the time that element gets visited. Deleted elements are visited as if they were undefined.
* @function
* @since 0.8.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the base type of array elements
* @typeParam E - Identifies a more specific instance of the base array type
* @param theArray - The array or array like object of elements to be searched.
* @param callbackFn - A function that accepts up to three arguments of type {@link ArrPredicateCallbackFn} or
* {@link ArrPredicateCallbackFn2}. The predicate function is called for each element in the thArray until
* the predicate returns a value which is coercible to the Boolean value false, or until the end of the array.
* @param thisArg - A value to use as this when executing callbackFn. Defaults to the array if not provided.
* @return The last element in the array that satisfies the provided testing function. Otherwise, undefined
* is returned.
* @example
* ```ts
* const inventory = [
* { name: "apples", quantity: 2 },
* { name: "bananas", quantity: 0 },
* { name: "cherries", quantity: 5 },
* ];
*
* function isCherries(fruit) {
* return fruit.name === "cherries";
* }
*
* console.log(arrFindLast(inventory, isCherries));
* // { name: 'cherries', quantity: 5 }
*
* function isPrime(element, index, array) {
* let start = 2;
* while (start <= Math.sqrt(element)) {
* if (element % start++ < 1) {
* return false;
* }
* }
* return element > 1;
* }
*
* console.log(arrFindLast([4, 6, 8, 12], isPrime)); // undefined, not found
* console.log(arrFindLast([4, 5, 7, 12], isPrime)); // 7
*
* // Array Like
* console.log(arrFindLast({ length: 4, 0: 4, 1: 6, 2: 8, 3: 12 }, isPrime)); // undefined, not found
* console.log(arrFindLast({ length: 4, 0: 4, 1: 5, 2: 7, 3: 12 }, isPrime)); // 7
* ```
*/
export declare const arrFindLast: <T, E extends T>(theArray: ArrayLike<T>, callbackFn: ArrPredicateCallbackFn<T, E> | ArrPredicateCallbackFn2<T>, thisArg?: any) => T | E;
/**
* The arrFindLastIndex() method iterates the array in reverse order and returns the index of the first element that
* satisfies the provided testing function. If no elements satisfy the testing function, -1 is returned.
*
* The arrFindLastIndex() method is an iterative method. It calls a provided `callbackFn` function once for each element
* in an array in descending-index order, until callbackFn returns a truthy value. arrFindLastIndex() then returns the
* index of that element and stops iterating through the array. If callbackFn never returns a truthy value, returns -1.
*
* `callbackFn` is invoked for every index of the array, not just those with assigned values. Empty slots in sparse arrays
* behave the same as undefined.
*
* arrFindLastIndex() does not mutate the array on which it is called, but the function provided as callbackFn can.
* Note, however, that the length of the array is saved before the first invocation of callbackFn. Therefore:
* - `callbackFn` will not visit any elements added beyond the array's initial length when the call to arrFindLastIndex() began.
* - Changes to already-visited indexes do not cause callbackFn to be invoked on them again.
* - If an existing, yet-unvisited element of the array is changed by `callbackFn`, its value passed to the callbackFn
* will be the value at the time that element gets visited. Deleted elements are visited as if they were undefined.
* @function
* @since 0.8.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the base type of array elements
* @typeParam E - Identifies a more specific instance of the base array type
* @param theArray - The array or array like object of elements to be searched.
* @param callbackFn - A function that accepts up to three arguments of type {@link ArrPredicateCallbackFn} or
* {@link ArrPredicateCallbackFn2}. The predicate function is called for each element in the thArray until
* the predicate returns a value which is coercible to the Boolean value false, or until the end of the array.
* @param thisArg - A value to use as this when executing callbackFn. Defaults to the array if not provided.
* @return The index of the last (highest-index) element in the array that passes the test. Otherwise -1 if
* no matching element is found.
* @example
* ```ts
* const inventory: Array<{ name: string, quantity: number}> = [
* { name: "apples", quantity: 2 },
* { name: "bananas", quantity: 0 },
* { name: "cherries", quantity: 5 }
* ];
*
* let called = 0;
* function isCherries(fruit: { name: string, quantity: number}) {
* called++;
* return fruit.name === "cherries";
* }
*
* arrFindLastIndex(inventory, isCherries)' // 2
* // called === 1
*
* called = 0;
* function isPrime(element: number) {
* called++;
* if (element % 2 === 0 || element < 2) {
* return false;
* }
* for (let factor = 3; factor <= Math.sqrt(element); factor += 2) {
* if (element % factor === 0) {
* return false;
* }
* }
* return true;
* }
*
* arrFindLastIndex([4, 6, 8, 9, 12], isPrime); // -1
* // called === 5
*
* called = 0;
* arrFindLastIndex([4, 6, 7, 9, 12], isPrime); // 2
* // called === 3
*
* // Array Like
* called = 0;
* arrFindLastIndex({ length: 5: 0: 4, 1: 6, 2: 8, 3: 9, 4: 12 }, isPrime); // -1
* // called === 5
*
* called = 0;
* arrFindLastIndex({ length: 5: 0: 4, 1: 6, 2: 7, 3: 9, 4: 12 }, isPrime); // 2
* // called === 3
* ```
*/
export declare const arrFindLastIndex: <T, E extends T>(theArray: ArrayLike<T>, callbackFn: ArrPredicateCallbackFn<T, E> | ArrPredicateCallbackFn2<T>, thisArg?: any) => number;
/**
* The arrFlatMap() method returns a new array formed by applying a mapping function to each element
* and then flattening the mapped result by one level.
*
* This is equivalent to calling `arrMap()` followed by `arrFlatten()` with a depth of 1, but it avoids
* allocating the intermediate mapped array.
*
* Use this helper when each input item may produce zero, one, or multiple output items as part of the
* mapping step. The mapped value is flattened by exactly one level: if the callback returns an array,
* its elements are appended to the output; non-array values are appended directly.
*
* To flatten already-nested data without mapping, use `arrFlatten()` instead.
*
* `callbackFn` is invoked only for indexes of the array which have assigned values. Empty slots in
* sparse arrays are skipped.
*
* @function
* @since 0.14.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the type of array elements
* @typeParam R - Identifies the type of the flattened result values, defaults to T.
* @param theArray - The array or array-like object to map and flatten.
* @param callbackFn - A function that is called for each existing element and may return either a
* single value or an array of values to flatten into the result.
* @param thisArg - The value to use as the `this` when executing the `callbackFn`.
* @returns A new array containing the mapped and flattened values.
* @example
* ```ts
* arrFlatMap([1, 2, 3], (value) => [value, value * 10]);
* // [1, 10, 2, 20, 3, 30]
*
* arrFlatMap(["one", "two"], (value) => value.split(""));
* // ["o", "n", "e", "t", "w", "o"]
*
* arrFlatMap({ length: 2, 0: "a", 1: "b" }, (value, index) => [index, value]);
* // [0, "a", 1, "b"]
*
* arrFlatMap([1, 2, 3, 4], (value) => value % 2 ? [value] : []);
* // [1, 3]
*
* arrFlatMap([1, 2], (value) => [[value, value + 10]] as any);
* // [[1, 11], [2, 12]]
* ```
*/
export declare const arrFlatMap: <T, R = T>(theArray: ArrayLike<T>, callbackFn: ArrFlatMapCallbackFn<T, R>, thisArg?: any) => R[];
/**
* Callback signature for {@link arrFlatMap}. Each invocation may return either a single value or
* an array of values to be flattened into the result by one level.
*
* @since 0.14.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the type of the array elements
* @typeParam R - Identifies the type of the flattened output values, defaults to T.
* @param value - The current element being processed in the array.
* @param index - The index of the current element being processed in the array.
* @param array - The array-like object that the `flatMap` function was called on.
*/
export declare type ArrFlatMapCallbackFn<T, R = T> = (value: T, index?: number, array?: ArrayLike<T>) => R | ReadonlyArray<R>;
/**
* The arrFlatten() method returns a new array with all sub-array elements flattened
* up to the specified depth (default 1).
*
* Use this helper when the input already contains nested arrays and you only need to
* control how deeply to flatten. Flattening is depth-based and only applies to values
* that are arrays; non-array values are copied into the output unchanged.
*
* For map-then-flatten workflows, use `arrFlatMap()` which always flattens mapped
* results by exactly one level.
* @function
* @since 0.14.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the base type of array elements
* @param theArray - The array or array-like object to flatten
* @param depth - The flattening depth, defaults to 1. Use Infinity for complete flattening
* @returns A new flattened array
* @example
* ```ts
* arrFlatten([1, [2, 3], [4, [5, 6]]]); // [1, 2, 3, 4, [5, 6]]
* arrFlatten([1, [2, 3], [4, [5, 6]]], 2); // [1, 2, 3, 4, 5, 6]
* arrFlatten([1, [2, 3], [4, [5, 6]]], Infinity); // [1, 2, 3, 4, 5, 6]
* arrFlatten([1, 2, 3]); // [1, 2, 3]
* arrFlatten([]); // []
*
* // With array-like objects
* arrFlatten({ length: 2, 0: 1, 1: [2, 3] }); // [1, 2, 3]
* ```
*/
export declare function arrFlatten<T>(theArray: ArrayLike<T | any[]> | null | undefined, depth?: number): any[];
/**
* Calls the provided `callbackFn` function once for each element in an array in ascending index order. It is not invoked for index properties
* that have been deleted or are uninitialized. And unlike the ES6 forEach() you CAN stop or break the iteration by returning -1 from the
* `callbackFn` function.
*
* The range (number of elements) processed by arrForEach() is set before the first call to the `callbackFn`. Any elements added beyond the range
* or elements which as assigned to indexes already processed will not be visited by the `callbackFn`.
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the element type of the array
* @param theArray - The array or array like object of elements to be searched.
* @param callbackfn - A `synchronous` function that accepts up to three arguments. arrForEach calls the callbackfn function one time for each element in the array.
* @param thisArg - An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, null or undefined
* the array will be used as the this value.
* @remarks
* arrForEach expects a `synchronous` function.
* arrForEach does not wait for promises. Make sure you are aware of the implications while using promises (or async functions) as forEach callback.
* @example
* ```ts
* const items = ['item1', 'item2', 'item3'];
* const copyItems = [];
*
* // before using for loop
* for (let i = 0; i < items.length; i++) {
* copyItems.push(items[i]);
* }
*
* // before using forEach()
* items.forEach((item) => {
* copyItems.push(item);
* });
*
* // after
* arrForEach(items, (item) => {
* copyItems.push(item);
* // May return -1 to abort the iteration
* });
*
* // Also supports input as an array like object
* const items = { length: 3, 0: 'item1', 1: 'item2', 2: 'item3' };
* ```
*/
export declare function arrForEach<T = any>(theArray: ArrayLike<T>, callbackfn: (value: T, index: number, array: T[]) => void | number, thisArg?: any): void;
export declare function arrForEach<T = any>(theArray: ArrayLike<T>, callbackfn: (value: T, index: number, array: ArrayLike<T>) => void | number, thisArg?: any): void;
/**
* Creates an new shallow-copied array from an array-like object or an iterable.
* @function
* @since 0.9.7
* @group ArrayLike
* @group Array
* @group Iterator
* @typeParam T - Identifies the element type of the array-like or iterable.
* @typeParam U - Identifies returned type of the array
* @param theValue - An array-like object or iterable to convert to an array.
* @param mapFn - A {@link ArrFromMapFn | mapping function} to call on every element of the array. If provided, every
* value to be added to the array is first passed through this map function, and the return
* value is added to the array instead. The function is called with the following arguments:
* @param thisArg - Value of 'this' used to invoke the mapfn.
* @example
* ```ts
* arrFrom("Hello");
* // [ "H", "e", "l", "l", "o" ]
*
* arrFrom(new Set(["Hello", "Darkness", "my", "old", "friend"]));
* // ["Hello", "Darkness", "my", "old", "friend"]
*
* let map = new Map([
* [ 1, "Hello" ],
* [ 2, "Darkness" ],
* [ 3, "my" ],
* [ 4, "old" ],
* [ 5, "friend"]
* ]);
*
* arrFrom(map.values());
* // ["Hello", "Darkness", "my", "old", "friend"]
*
* arrFrom(map.keys());
* // [ 1, 2, 3, 4, 5 ]
*
* arrFrom(map.entries());
* // [ [ 1, "Hello" ], [ 2, "Darkness" ], [ 3, "my" ], [ 4, "old" ], [ 5, "friend"] ]
*
* // With a Mapping function
* const map = new Map([
* [ 1, "Hello" ],
* [ 2, "Darkness" ],
* [ 3, "my" ],
* [ 4, "old" ],
* [ 5, "friend"]
* ]);
*
* arrFrom(map, ([ key, value ]) => ({ [key]: value }));
* // [ {"1": "Hello"}, {"2": "Darkness"}, {"3": "my"}, {"4": "old"}, {"5": "friend"} ]
* ```
*/
export declare const arrFrom: <T, U = T>(theValue: ArrayLike<T> | Iterable<T>, mapFn?: ArrFromMapFn<T, U>, thisArg?: any) => U[];
/**
* Callback signature for {@link arrFrom} mapFn that is called for every element of array. Each time mapFn
* executes, the returned value is added to newArray.
*
* @since 0.9.7
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the type of the array elements
* @typeParam R - Identifies the type of the elements returned by the map function, defaults to T.
* @param value - The current element being processed in the array.
* @param index - The index of the current element being processed in the array.
*/
export declare type ArrFromMapFn<T, R = T> = (value: T, index?: number) => R;
/**
* The arrGroupBy() method groups array elements by the result of a callback function,
* returning an object where keys are group identifiers and values are arrays of grouped elements.
* @function
* @since 0.14.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the base type of array elements
* @param theArray - The array or array-like object to group
* @param callbackFn - Function that determines the group key for each element
* @param thisArg - The value to use as 'this' when executing callbackFn
* @returns An object with group keys as properties and arrays of grouped elements as values
* @example
* ```ts
* const numbers = [1, 2, 3, 4, 5, 6];
* const grouped = arrGroupBy(numbers, (n) => n % 2 === 0 ? "even" : "odd");
* // { odd: [1, 3, 5], even: [2, 4, 6] }
*
* const people = [
* { name: "Alice", age: 30 },
* { name: "Bob", age: 25 },
* { name: "Charlie", age: 30 }
* ];
* const byAge = arrGroupBy(people, (p) => p.age);
* // { "25": [{ name: "Bob", age: 25 }], "30": [{ name: "Alice", age: 30 }, { name: "Charlie", age: 30 }] }
* ```
*/
export declare function arrGroupBy<T>(theArray: ArrayLike<T> | null | undefined, callbackFn: ArrGroupByCallbackFn<T>, thisArg?: any): Record<string | number | symbol, T[]>;
/**
* Callback function type used by {@link arrGroupBy} to derive a group key for each element.
* The function is called once per element and must return a `string`, `number`, or `symbol`
* that identifies which group the element belongs to. Elements that map to the same key are
* collected into the same array in the result object.
* @since 0.14.0
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the base type of array elements
* @param value - The current element of the array being processed.
* @param index - The zero-based index of the current element in the array.
* @param array - The array (or array-like object) that {@link arrGroupBy} was called on.
* @returns A `string`, `number`, or `symbol` that identifies the group for the current element.
* @example
* ```ts
* // Group numbers as "even" or "odd"
* const parity: ArrGroupByCallbackFn<number> = (n) => n % 2 === 0 ? "even" : "odd";
*
* arrGroupBy([1, 2, 3, 4, 5], parity);
* // { odd: [1, 3, 5], even: [2, 4] }
* ```
* @example
* ```ts
* // Group objects by a property value
* interface Person { name: string; dept: string; }
*
* const byDept: ArrGroupByCallbackFn<Person> = (p) => p.dept;
*
* const people: Person[] = [
* { name: "Alice", dept: "eng" },
* { name: "Bob", dept: "hr" },
* { name: "Carol", dept: "eng" }
* ];
*
* arrGroupBy(people, byDept);
* // {
* // eng: [{ name: "Alice", dept: "eng" }, { name: "Carol", dept: "eng" }],
* // hr: [{ name: "Bob", dept: "hr" }]
* // }
* ```
* @example
* ```ts
* // Use the element index to create fixed-size buckets
* const bucket: ArrGroupByCallbackFn<string> = (_v, idx) => idx % 3;
*
* arrGroupBy(["a", "b", "c", "d", "e"], bucket);
* // { 0: ["a", "d"], 1: ["b", "e"], 2: ["c"] }
* ```
*/
export declare type ArrGroupByCallbackFn<T> = (value: T, index: number, array: ArrayLike<T>) => string | number | symbol;
/**
* The arrIncludes() method determines whether an array includes a certain value among its
* entries, returning true or false as appropriate.
* @function
* @since 0.8.0
* @group Array
* @group ArrayLike
* @param theArray - The array or array like object of elements to be searched.
* @param searchElement - The value to search for
* @param fromIndex - The optional Zero-based index at which to start searching, converted to an integer.
* - Negative index counts back from the end of the array — if fromIndex \< 0, fromIndex + array.length
* is used. However, the array is still searched from front to back in this case.
* - If fromIndex \< -array.length or fromIndex is omitted, 0 is used, causing the entire array to be searched.
* - If fromIndex \>= array.length, the array is not searched and false is returned.
* @returns A boolean value which is true if the value searchElement is found within the array (or the part of
* the array indicated by the index fromIndex, if specified).
* @example
* ```ts
* arrIncludes([1, 2, 3], 2); // true
* arrIncludes([1, 2, 3], 4); // false
* arrIncludes([1, 2, 3], 3, 3); // false
* arrIncludes([1, 2, 3], 3, -1); // true
* arrIncludes([1, 2, NaN], NaN); // true
* arrIncludes(["1", "2", "3"], 3 as any); // false
*
* // Array Like
* arrIncludes({ length: 3, 0: 1, 1: 2, 2: 3 }, 2); // true
* arrIncludes({ length: 3, 0: 1, 1: 2, 2: 3 }, 4); // false
* arrIncludes({ length: 3, 0: 1, 1: 2, 2: 3 }, 3, 3); // false
* arrIncludes({ length: 3, 0: 1, 1: 2, 2: 3 }, 3, -1); // true
* arrIncludes({ length: 3, 0: 1, 1: 2, 2: NaN }, NaN); // true
* arrIncludes({ length: 3, 0: "1", 1: "2", 2: "3" }, 3 as any); // false
* ```
*/
export declare const arrIncludes: <T>(theArray: ArrayLike<T>, searchElement: T, fromIndex?: number) => boolean;
/**
* Returns only present own numeric index keys for an array-like value.
*
* Unlike {@link arrKeys}, this skips holes / missing indexes.
* For example, an array with indexes `0`, `1`, `2`, `10` returns `[0, 1, 2, 10]`.
* @since 0.14.0
* @group Array
* @group ArrayLike
* @param value - The array-like value to enumerate.
* @returns An array containing only present own numeric index keys.
* @example
* ```ts
* arrIndexKeys(["a", "b", "c"]);
* // [0, 1, 2]
*
* const sparse: any[] = [];
* sparse[0] = "a";
* sparse[10] = "z";
* arrIndexKeys(sparse);
* // [0, 10]
* ```
*/
export declare function arrIndexKeys<T = any>(value: ArrayLike<T>): number[];
/**
* The arrIndexOf() method returns the first index at which a given element can be found in the array,
* or -1 if it is not present.
* `arrIndexOf()` compares searchElement to elements of the Array using strict equality (the same
* method used by the === or triple-equals operator).
* @function
* @group Array
* @group ArrayLike
* @typeParam T - Identifies the type of array elements
* @param theArray - The array or array like object of elements to be searched.
* @param searchElement - The element to locate in the array.
* @param fromIndex - The index to start the search at. If the index is greater than or equal to
* the array's length, -1 is returned, which means the array will not be searched. If the provided
* index value is a negative number, it is taken as the offset from the end of the array.
* Note: if the provided index is negative, the array is still searched from front to back. If the
* provided index is 0, then the whole array will be searched. Default: 0 (entire array is searched).
* @return The first index of the element in the array; -1 if not found.
* @example
* ```ts
* const array = [2, 9, 9];
* arrIndexOf(array, 2); // 0
* arrIndexOf(array, 7); // -1
* arrIndexOf(array, 9, 2); // 2
* arrIndexOf(array, 2, -1); // -1
* arrIndexOf(array, 2, -3); // 0
*
* let indices: number[] = [];
* const array = ['a', 'b', 'a', 'c', 'a', 'd'];
* const element = 'a';
* let idx = arrIndexOf(array, element);
* while (idx !== -1) {
* indices.push(idx);
* idx = arrIndexOf(array, element, idx + 1);
* }
* console.log(indices);
* // [0, 2, 4]
*
* function updateVegetablesCollection (veggies, veggie) {
* if (arrIndexOf(veggies, veggie) === -1) {
* veggies.push(veggie);
* console.log('New veggies collection is : ' + veggies);
* } else {
* console.log(veggie + ' already exists in the veggies collection.');
* }
* }
*
* let veggies = ['potato', 'tomato', 'chillies', 'green-pepper'];
*
* updateVegetablesCollection(veggies, 'spinach');
* // New veggies collection is : potato,tomato,chillies,green-pepper,spinach
* updateVegetablesCollection(veggies, 'spinach');
* // spinach already exists in the veggies collection.
*
* // Array Like
* let arrayLike = {
* length: 3,
* 0: "potato",
* 1: "tomato",
* 2: "chillies",
* 3: "green-pepper" // Not checked as index is > length
* };
*
* arrIndexOf(arrayLike, "potato"); // 0
* arrIndexOf(arrayLike, "tomato"); // 1
* arrIndexOf(arrayLike, "chillies"); 2
* arrIndexOf(arrayLike, "green-pepper"); // -