topkat-utils/dist/src/array-utils.d.ts

A comprehensive collection of TypeScript/JavaScript utility functions for common programming tasks. Includes validation, object manipulation, date handling, string formatting, and more. Zero dependencies, fully typed, and optimized for performance.

/** Randomize array in place and return the same array than inputed */
export declare function shuffleArray<EntryArray extends any[]>(array: EntryArray): EntryArray;
/**
 * Maye sure obj[addr] is an array and push a value to it
 * @param {Object} obj parent object
 * @param {String} addr field name in parent
 * @param {Any} valToPush
 * @param {Boolean} onlyUniqueValues default:false; may be true or a comparision function; (a,b) => return true if they are the same like (a, b) => a.name === b.name
 * @return obj[addr] eventually processed by the callback
 */
export declare function ensureIsArrayAndPush(obj: object, addr: string, valToPush: any, onlyUniqueValues?: Function): unknown;
/** If a string is provided, return it as array else return the value */
export declare function strAsArray<T>(arrOrStr: T): T extends string ? string[] : T;
type AsArrReturnVal<T, X> = T extends undefined ? (X extends undefined ? void : X) : T extends any[] ? T : T[];
/** If not an array provided, return the array with the value
 * /!\ NOTE /!\ In case the value is null or undefined, it will return that value
 */
export declare function asArray<T extends any[] | any, X>(item: T, returnValueIfUndefined?: X): AsArrReturnVal<T, X>;
/** @return {object} { inCommon, notInB, notInA } */
export declare function compareArrays<T1, T2>(arrayA?: T1[] | readonly T1[], arrayB?: T2[] | readonly T2[], compare?: (a: T1 | T2, b: T1 | T2) => boolean): {
    inCommon: ReturnType<typeof getArrayInCommon<T1, T2>>;
    notInB: ReturnType<typeof getArrayInCommon<T1, T2>>;
    notInA: ReturnType<typeof getArrayInCommon<T2, T1>>;
};
/** @return [] only elements that are both in arrayA and arrayB  */
export declare function getArrayInCommon<T1, T2>(arrayA?: T1[] | readonly T1[], arrayB?: T2[] | readonly T2[], compare?: (a: T1 | T2, b: T1 | T2) => boolean): T1[];
/** @return [] only elements that are in arrayB and not in arrayA */
export declare function getNotInArrayA<T1, T2>(arrayA?: T1[] | readonly T1[], arrayB?: T2[] | readonly T2[], compare?: (a: T1 | T2, b: T1 | T2) => boolean): T2[];
/**
 * @return [] only elements that are in neither arrayA and arrayB
 */
export declare function getArrayDiff<T1, T2>(arrayA?: T1[] | readonly T1[], arrayB?: T2[] | readonly T2[], compare?: (a: T1 | T2, b: T1 | T2) => boolean): (T1 | T2)[];
/** filter duplicate values in an array
 * @param {function} comparisonFn default:(a, b) => a === b. A function that shall return true if two values are considered equal
 * @return {array|function}
 */
export declare function noDuplicateFilter<T extends any[] | readonly any[]>(arr: T, comparisonFn?: (a: T, b: T) => boolean): T;
/** Count number of occurence of item in array */
export declare function arrayCount(item: any, arr: any[] | readonly any[]): number;
/**
 * @param {Function} comparisonFunction default: (itemToPush, itemAlreadyInArray) => itemToPush === itemAlreadyInArray; comparison function to consider the added item duplicate
 */
export declare function pushIfNotExist<T>(arrayToPushInto: T[], valueOrArrayOfValuesToBePushed: T | T[], comparisonFunction?: (a: T, b: T) => boolean): T[];
export declare function isNotEmptyArray(arr: any[]): boolean;
export declare function randomItemInArray<T extends Array<any> | (readonly any[])>(array: T): T[number];
/** This has been made because in typescript the FUCKING TYPE OF THE ITEM must be typê of InputArray[number] which is shit since you want to know if the item is included and it may be of any type. In bonus, if type is included in the array, the type will be true */
export declare function includes<A extends any[] | readonly any[], B>(array: A, item: B): B extends A[number] ? true : boolean;
export {};