@ugo-code/streamline.js/dist/cjs/array.d.ts

A utility module which provides straight-forward, powerful functions for working with asynchronous JavaScript

/**
 * An extended Array class providing convenient getters and powerful utility methods.
 * It's fully generic, type-safe, and designed for seamless method chaining.
 *
 * @template T The type of elements in the array. Defaults to `unknown`.
 */
export declare class ArraySL<T = unknown> extends Array<T> {
    /**
     * Creates a new ArraySL instance. This constructor is compatible with the
     * standard Array constructor signatures.
     */
    constructor(item?: Iterable<T> | number);
    /**
     * Ensures that methods inherited from Array (like .map, .filter, .slice)
     * return an instance of ArraySL instead of a plain Array. This makes
     * method chaining seamless.
     */
    static get [Symbol.species](): ArrayConstructor;
    /**
     * Returns the first element of the array.
     * @returns {T | undefined} The first element, or `undefined` if the array is empty.
     */
    get first(): T | undefined;
    /**
     * Returns the last element of the array.
     * @returns {T | undefined} The last element, or `undefined` if the array is empty.
     */
    get last(): T | undefined;
    /**
     * Returns a random element from the array.
     * @returns {T | undefined} A random element, or `undefined` if the array is empty.
     */
    get random(): T | undefined;
    /**
     * Returns the middle item or items of the array based on their index.
     *
     * This method finds the element(s) at the center of the array without any sorting.
     * - If the array has an odd number of elements, it returns the single middle item.
     * - If the array has an even number of elements, it returns the two middle items.
     *
     * This is distinct from a median calculation, which would require the array to be sorted by value first.
     *
     * @returns {ArraySL<T>} A new ArraySL containing the middle item(s). Returns an empty array if the source array is empty.
     * @example
     * // For an array with an odd length
     * const oddList = new ArraySL(['a', 'b', 'c', 'd', 'e']);
     * console.log(oddList.middle()); // Returns ArraySL['c']
     *
     * // For an array with an even length
     * const evenList = new ArraySL([10, 20, 30, 40]);
     * console.log(evenList.middle()); // Returns ArraySL[20, 30]
     *
     * // For an empty array
     * const emptyList = new ArraySL([]);
     * console.log(emptyList.middle()); // Returns ArraySL[]
     */
    middle(): ArraySL<T>;
    /**
     * Returns a new ArraySL containing only the unique elements from the original array.
     * Uniqueness is based on the element itself or on a key generated by the provided accessor.
     * This method is highly performant (O(n)).
     *
     * @param options An optional configuration object.
     *   - `accessor`: An optional function that takes an element and returns a value to be used
     *     for the uniqueness check. If not provided, the element itself is used. Keys that are
     *     objects or arrays are compared by their JSON string representation.
     * @returns {ArraySL<T>} A new ArraySL instance with duplicate elements removed.
     */
    unique(options?: {
        accessor?: (value: T, index: number, array: T[]) => any;
    }): ArraySL<T>;
    /**
     * Returns a new ArraySL containing duplicate elements from the original array.
     * This method is highly configurable and performant, operating in a single pass (O(n)).
     *
     * @param options An optional configuration object.
     *   - `accessor`: An optional function that takes an element and returns a value to be used
     *     for the uniqueness check. If not provided, the element itself is used. Keys that are
     *     objects or arrays are compared by their JSON string representation.
     *   - `mode`: Determines which duplicate items to include in the result.
     *      - 'all' (default): Returns all instances of items that are duplicates.
     *      - 'first': Returns only the first instance of each duplicated item.
     *      - 'subsequent': Returns only the duplicate instances that appear after the first one.
     * @returns {ArraySL<T>} A new ArraySL instance containing the specified duplicate elements.
     */
    duplicates(options?: {
        accessor?: (value: T, index: number, array: T[]) => any;
        mode?: "first" | "subsequent" | "all";
    }): ArraySL<T>;
    /**
     * Finds the most frequently occurring item(s) in the array.
     *
     * This method identifies which items appear most often, based on the item itself or a
     * key extracted from the item. If multiple items share the same highest frequency,
     * all of them are returned.
     *
     * @param accessor An optional function to extract a comparable key from an item. If not provided,
     *   the item itself is used for comparison.
     * @returns {ArraySL<T>} A new ArraySL containing the most frequent item(s).
     *   Returns an empty array if there is no unique most frequent item (e.g., in `[1, 1, 2, 2]`).
     * @example
     * const users = new ArraySL([
     *   { name: 'Alice', city: 'Paris' },
     *   { name: 'Bob', city: 'Tokyo' },
     *   { name: 'Charlie', city: 'Paris' }
     * ]);
     * console.log(users.mostFrequent((u) => u.city)); // Returns ArraySL containing the 'Alice' and 'Charlie' objects
     *
     * const numbers = new ArraySL([1, 2, 2, 3, 3, 3]);
     * console.log(numbers.mostFrequent()); // Returns ArraySL[3, 3, 3]
     */
    mostFrequent(accessor?: (value: T, index: number, array: T[]) => any): ArraySL<T>;
    filter<S extends T>(predicate: (value: T, index: number, array: T[]) => value is S, thisArg?: any): ArraySL<S>;
    filter(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): ArraySL<T>;
    map<U>(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any): ArraySL<U>;
    slice(start?: number, end?: number): ArraySL<T>;
    concat(...items: ConcatArray<T>[]): ArraySL<T>;
}