@ayonli/jsext/types/augment/array.d.ts

A JavaScript extension package for building strong and modern applications.

declare global {
    interface Array<T> {
        /** Returns the first element of the array, or `undefined` if the array is empty. */
        first(): T | undefined;
        /** Returns the last element of the array, or `undefined` if the array is empty. */
        last(): T | undefined;
        /** Returns a random element of the array, or `undefined` if the array is empty. */
        random(remove?: boolean): T | undefined;
        /** Counts the occurrence of the element in the array. */
        count(item: T): number;
        /**
         * Performs a shallow compare to another array and see if it contains the same elements as
         * this array.
         */
        equals(another: T[]): boolean;
        /** Checks if the array contains another array as a slice of its contents. */
        includesSlice<T>(slice: T[]): boolean;
        /** Checks if the array starts with the given prefix. */
        startsWith<T>(prefix: T[]): boolean;
        /** Checks if the array ends with the given suffix. */
        endsWith<T>(suffix: T[]): boolean;
        /** Breaks the array into smaller chunks according to the given delimiter. */
        split(delimiter: T): T[][];
        /** Breaks the array into smaller chunks according to the given length. */
        chunk(length: number): T[][];
        /** Returns a subset of the array that contains only unique items. */
        unique(): T[];
        /**
         * @deprecated use `unique` instead.
         */
        uniq(): T[];
        /**
         * Returns a subset of the array that contains only unique items filtered by the
         * given callback function.
         */
        uniqueBy<K extends string | number | symbol>(fn: (item: T, i: number) => K): T[];
        /**
         * @deprecated use `uniqueBy` instead.
         */
        uniqBy<K extends string | number | symbol>(fn: (item: T, i: number) => K): T[];
        /**
         * Reorganizes the elements in the array in random order.
         *
         * This function mutates the array.
         */
        shuffle(): T[];
        toShuffled(): T[];
        toReversed(): T[];
        toSorted(fn?: ((a: T, b: T) => number) | undefined): T[];
        /** Orders the items of the array according to the given callback function. */
        orderBy(fn: (item: T, i: number) => string | number | bigint, order?: "asc" | "desc"): T[];
        /**
         * Orders the items of the array according to the specified comparable `key`
         * (whose value must either be a numeric or string).
         *
         * @deprecated This signature is not in line with other functions, such as
         * {@link groupBy} and {@link keyBy}, use the callback form instead.
         */
        orderBy(key: keyof T, order?: "asc" | "desc"): T[];
        /**
         * Groups the items of the array according to the comparable values returned by a provided
         * callback function.
         *
         * The returned record / map has separate properties for each group, containing arrays with
         * the items in the group.
         */
        groupBy<K extends string | number | symbol>(fn: (item: T, i: number) => K, type?: ObjectConstructor): Record<K, T[]>;
        groupBy<K>(fn: (item: T, i: number) => K, type: MapConstructor): Map<K, T[]>;
        /**
         * Creates a record or map from the items of the array according to the comparable values
         * returned by a provided callback function.
         *
         * This function is similar to {@link groupBy} except it overrides values if the same
         * property already exists instead of grouping them as a list.
         */
        keyBy<K extends string | number | symbol>(fn: (item: T, i: number) => K, type?: ObjectConstructor): Record<K, T>;
        keyBy<K>(fn: (item: T, i: number) => K, type: MapConstructor): Map<K, T>;
        /**
         * Returns a tuple of two arrays with the first one containing all elements in
         * the given array that match the given predicate and the second one containing
         * all that do not.
         */
        partition(predicate: (item: T, i: number) => boolean): [T[], T[]];
    }
}
export {};