@aedart/support/dist/types/arrays.d.ts

The Ion support package

/**
 * @aedart/support
 * 
 * BSD-3-Clause, Copyright (c) 2023-present Alin Eugen Deac <aedart@gmail.com>.
 */

import { ArrayMerger, ArrayMergeOptions, ArrayMergeCallback, ArrayMergeException } from '@aedart/contracts/support/arrays';

/**
 * Determine if array includes all given values
 *
 * @param {any[]} arr
 * @param {any[]} values
 *
 * @return {boolean}
 */
declare function includesAll(arr: any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ values: any[]): boolean;

/**
 * Determine if array includes any (_some_) of the given values
 *
 * @param {any[]} arr
 * @param {any[]} values
 *
 * @return {boolean}
 */
declare function includesAny(arr: any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ values: any[]): boolean;

/**
 * Determine if value is "array-like".
 * (Alias for Lodash's [`isArrayLike`]{@link import('lodash').isArrayLike}) method.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#array-like_objects
 * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Indexed_collections#working_with_array-like_objects
 *
 * @param {any} value
 *
 * @return {boolean}
 */
declare const isArrayLike: {
    <T extends {
        __lodashAnyHack: any;
    }>(t: T): boolean;
    (value: ((...args: any[]) => any) | null | undefined): value is never;
    (value: any): value is {
        length: number;
    };
};

/**
 * Determine if target object contains the well-known symbol {@link Symbol.isConcatSpreadable}
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/isConcatSpreadable
 *
 * @param {object} target
 *
 * @return {boolean}
 */
declare function isConcatSpreadable(target: object): boolean;

/**
 * Determine if value is "safe" array-like object
 *
 * **Note**: _In this context "safe" means that given object passes {@link isArrayLike},
 * but value is:_
 *  - not a string.
 *  - not instance of a {@link String} object.
 *  - not a [Typed Array]{@link isTypedArray} object.
 *
 * @param {object} value
 *
 * @return {boolean}
 */
declare function isSafeArrayLike(value: any): boolean;

/**
 * Determine if given target is an instance of a `TypedArray`
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
 *
 * @param {object} target
 *
 * @return {boolean}
 */
declare function isTypedArray(target: object): boolean;

/**
 * Returns new Array Merger instance
 *
 * @return {ArrayMerger}
 */
declare function merge(): ArrayMerger;
/**
 * Returns a merger of given source arrays
 *
 * @template SourceA extends any[]
 *
 * @param {SourceA} a
 *
 * @returns {SourceA}
 *
 * @throws {ArrayMergeException}
 */
declare function merge<SourceA extends any[]>(a: SourceA): SourceA;
/**
 * Returns a merger of given source arrays
 *
 * @template SourceA extends any[]
 * @template SourceB extends any[]
 *
 * @param {SourceA} a
 * @param {SourceB} b
 *
 * @returns {SourceA & SourceB}
 *
 * @throws {ArrayMergeException}
 */
declare function merge<SourceA extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceB extends any[]>(a: SourceA, b: SourceB): SourceA & SourceB;
/**
 * Returns a merger of given source arrays
 *
 * @template SourceA extends any[]
 * @template SourceB extends any[]
 * @template SourceC extends any[]
 *
 * @param {SourceA} a
 * @param {SourceB} b
 * @param {SourceC} c
 *
 * @returns {SourceA & SourceB & SourceC}
 *
 * @throws {ArrayMergeException}
 */
declare function merge<SourceA extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceB extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceC extends any[]>(a: SourceA, b: SourceB, c: SourceC): SourceA & SourceB & SourceC;
/**
 * Returns a merger of given source arrays
 *
 * @template SourceA extends any[]
 * @template SourceB extends any[]
 * @template SourceC extends any[]
 * @template SourceD extends any[]
 *
 * @param {SourceA} a
 * @param {SourceB} b
 * @param {SourceC} c
 * @param {SourceD} d
 *
 * @returns {SourceA & SourceB & SourceC & SourceD}
 *
 * @throws {ArrayMergeException}
 */
declare function merge<SourceA extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceB extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceC extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceD extends any[]>(a: SourceA, b: SourceB, c: SourceC, d: SourceD): SourceA & SourceB & SourceC & SourceD;
/**
 * Returns a merger of given source arrays
 *
 * @template SourceA extends any[]
 * @template SourceB extends any[]
 * @template SourceC extends any[]
 * @template SourceD extends any[]
 * @template SourceE extends any[]
 *
 * @param {SourceA} a
 * @param {SourceB} b
 * @param {SourceC} c
 * @param {SourceD} d
 * @param {SourceE} e
 *
 * @returns {SourceA & SourceB & SourceC & SourceD & SourceE}
 *
 * @throws {ArrayMergeException}
 */
declare function merge<SourceA extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceB extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceC extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceD extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceE extends any[]>(a: SourceA, b: SourceB, c: SourceC, d: SourceD, e: SourceE): SourceA & SourceB & SourceC & SourceD & SourceE;
/**
 * Returns a merger of given source arrays
 *
 * @template SourceA extends any[]
 * @template SourceB extends any[]
 * @template SourceC extends any[]
 * @template SourceD extends any[]
 * @template SourceE extends any[]
 * @template SourceF extends any[]
 *
 * @param {SourceA} a
 * @param {SourceB} b
 * @param {SourceC} c
 * @param {SourceD} d
 * @param {SourceE} e
 * @param {SourceF} f
 *
 * @returns {SourceA & SourceB & SourceC & SourceD & SourceE & SourceF}
 *
 * @throws {ArrayMergeException}
 */
declare function merge<SourceA extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceB extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceC extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceD extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceE extends any[], /* eslint-disable-line @typescript-eslint/no-explicit-any */ SourceF extends any[]>(a: SourceA, b: SourceB, c: SourceC, d: SourceD, e: SourceE, f: SourceF): SourceA & SourceB & SourceC & SourceD & SourceE & SourceF;

/**
 * Default Array Merge Options
 */
declare class DefaultArrayMergeOptions implements ArrayMergeOptions {
    /**
     * Transfer functions
     *
     * **When `true`**: _functions are transferred into resulting array._
     *
     * **When `false` (_default behaviour_)**: _The merge operation will fail when a function
     * is encountered (functions are not cloneable by default)._
     *
     * @type {boolean}
     */
    transferFunctions: boolean;
    /**
     * Merge callback to be applied
     *
     * **Note**: _When no callback is provided, then the merge function's default
     * callback is used._
     */
    callback: ArrayMergeCallback;
    /**
     * Create new default merge options from given options
     *
     * @param {ArrayMergeCallback | ArrayMergeOptions} [options]
     */
    constructor(options?: ArrayMergeCallback | ArrayMergeOptions);
    /**
     * Create new default merge options from given options
     *
     * @param {ArrayMergeOptions} [options]
     *
     * @return {Readonly<DefaultArrayMergeOptions|ArrayMergeOptions>}
     */
    static from(options?: ArrayMergeCallback | ArrayMergeOptions): Readonly<DefaultArrayMergeOptions | ArrayMergeOptions>;
}

/**
 * Array Merger
 */
declare class Merger implements ArrayMerger {
    /**
     * Merge options to be applied
     *
     * @type {Readonly<DefaultArrayMergeOptions | ArrayMergeOptions>}
     *
     * @protected
     */
    protected _options: Readonly<DefaultArrayMergeOptions | ArrayMergeOptions>;
    /**
     * Create new Array Merger instance
     *
     * @param {ArrayMergeCallback | ArrayMergeOptions} [options]
     */
    constructor(options?: ArrayMergeCallback | ArrayMergeOptions);
    /**
     * Use the following merge options
     *
     * @param {ArrayMergeCallback | ArrayMergeOptions} [options]
     *
     * @return {this}
     *
     * @throws {ArrayMergeException}
     */
    using(options?: ArrayMergeCallback | ArrayMergeOptions): this;
    /**
     * Merge options to be applied
     *
     * @type {Readonly<DefaultArrayMergeOptions | ArrayMergeOptions>}
     */
    get options(): Readonly<DefaultArrayMergeOptions | ArrayMergeOptions>;
    /**
     * Returns a merger of given source arrays
     *
     * @param {...any[]} sources
     *
     * @return {any[]}
     *
     * @throws {ArrayMergeException}
     */
    of(...sources: any[]): any[];
    /**
     * Resolves options
     *
     * @param {ArrayMergeCallback | ArrayMergeOptions} options
     *
     * @return {Readonly<ArrayMergeOptions>}
     *
     * @protected
     */
    protected resolveOptions(options?: ArrayMergeCallback | ArrayMergeOptions): Readonly<DefaultArrayMergeOptions | ArrayMergeOptions>;
}

/**
 * Default Array Merge callback
 *
 * @param {any} element
 * @param {number} index
 * @param {any[]} array
 * @param {Readonly<ArrayMergeOptions>} options
 *
 * @return {any}
 */
declare const defaultArrayMergeCallback: ArrayMergeCallback;

/**
 * Array Merge Error
 *
 * To be thrown when two or more arrays are unable to be merged.
 */
declare class ArrayMergeError extends Error implements ArrayMergeException {
    /**
     * Create a new Array Merge Error instance
     *
     * @param {string} [message]
     * @param {ErrorOptions} [options]
     */
    constructor(message?: string, options?: ErrorOptions);
}

export { ArrayMergeError, DefaultArrayMergeOptions, Merger, defaultArrayMergeCallback, includesAll, includesAny, isArrayLike, isConcatSpreadable, isSafeArrayLike, isTypedArray, merge };