sorted-array-type/dist/src/index.d.ts

Array with sorted insertion and optimized search methods.

/** See {@link SortedArray.EqualityFunction}. */
export type SortedArrayEqualityFunction<T> = (a: T, b: T) => unknown;
/** See {@link SortedArray.ComparatorFunction}. */
export type SortedArrayComparatorFunction<T> = (a: T, b: T) => number;
/** See {@link SortedArray.DefaultEqualityFunction}. */
export declare const SortedArrayDefaultEqualityFunction: SortedArrayEqualityFunction<unknown>;
/** See {@link SortedArray.DefaultComparatorFunction}. */
export declare const SortedArrayDefaultComparatorFunction: SortedArrayComparatorFunction<unknown>;
/** See {@link SortedArray.ElementCallback}. */
export type SortedArrayElementCallback<This, T, U> = ((this: This, value: T, index: number, array: SortedArray<T>) => U);
/**
 * The SortedArray type is a subclass of the base JavaScript Array
 * type whose elements are kept in a sorted order.
 *
 * Methods like {@link SortedArray.insert} are provided as an
 * alternative to the typical array `push` method for inserting
 * new elements in sorted order.
 *
 * Some methods, such as {@link SortedArray.indexOf} provide
 * optimized implementations of Array methods, which may operate
 * more efficiently upon sorted lists.
 *
 * **Warning:** The SortedArray type does not stop you
 * from still calling methods like `push`, `shift`, or `splice`,
 * which may invalidate the assumptions that SortedArray methods
 * make about array contents being correctly sorted.
 * These methods should be used with care, if they are used at all.
 * Invalidating the sort order of a SortedArray will cause many
 * operations to behave in unexpected ways.
 */
export declare class SortedArray<T> extends Array<T> {
    /** Equality function used by the SortedArray. */
    equalityFunc: SortedArrayEqualityFunction<T>;
    /** Comparator function used by the SortedArray. */
    compareFunc: SortedArrayComparatorFunction<T>;
    /** May refer to a reversed version of the SortedArray's comparator function. */
    reversedCompareFunc: SortedArrayComparatorFunction<T> | undefined;
    /**
     * Construct a new empty SortedArray, using the default comparator
     * and equality functions.
     */
    constructor();
    /**
     * Construct a new SortedArray with the given length.
     */
    constructor(length: number);
    /**
     * Construct a new empty SortedArray, optionally specifying a
     * custom comparator function or a custom equality function.
     *
     * The SortedArray implementation assumes that any values `a` and `b`
     * for which `equalityFunc(a, b) === true`,
     * it is also the case that `compareFunc(a, b) === 0`.
     *
     * @param compareFunc A custom comparator function, to use instead of
     * {@link SortedArray.DefaultComparatorFunction}.
     * The comparator function determines the sort order of items in
     * the array.
     * @param equalityFunc A custom equality function, to use instead of
     * {@link SortedArray.DefaultEqualityFunction}.
     */
    constructor(compareFunc?: SortedArrayComparatorFunction<T>, equalityFunc?: SortedArrayEqualityFunction<T>);
    /**
     * Construct a new SortedArray from the given items, which will
     * be sorted using the Array `sort` function.
     * This is not guaranteed to be stable in all cases. See:
     * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#sort_stability
     *
     * The SortedArray implementation assumes that any values `a` and `b`
     * for which `equalityFunc(a, b) === true`,
     * it is also the case that `compareFunc(a, b) === 0`.
     *
     * @param items An iterable of items to initially insert into the
     * constructed SortedArray.
     * @param compareFunc A custom comparator function, to use instead of
     * {@link SortedArray.DefaultComparatorFunction}.
     * The comparator function determines the sort order of items in
     * the array.
     * @param equalityFunc A custom equality function, to use instead of
     * {@link SortedArray.DefaultEqualityFunction}.
     */
    constructor(items: Iterable<T> | ArrayLike<T>, compareFunc?: SortedArrayComparatorFunction<T>, equalityFunc?: SortedArrayEqualityFunction<T>);
    /**
     * Construct a new SortedArray and insert the given values.
     *
     * @param values The values that should be inserted and sorted in
     * the newly constructed SortedArray.
     *
     * @returns the newly constructed SortedArray, containing the given
     * values in sorted order.
     */
    static of<T>(...values: T[]): SortedArray<T>;
    /**
     * Construct a new SortedArray, initializing it with some values
     * that are already provided in sorted order.
     *
     * @param values The values that should be inserted in the newly
     * constructed SortedArray. They must be sorted according to
     * {@link SortedArray.DefaultComparatorFunction}, otherwise the
     * returned SortedArray may behave unexpectedly.
     *
     * @returns the newly constructed SortedArray, containing the given
     * assumed-sorted values.
     */
    static ofSorted<T>(...values: T[]): SortedArray<T>;
    /**
     * Construct a new SortedArray and insert the values in an iterable
     * or array-like object.
     *
     * @param values The values that should be inserted and sorted in
     * the newly constructed SortedArray.
     * @param compareFunc A custom comparator function, to use instead of
     * {@link SortedArray.DefaultComparatorFunction}.
     * @param equalityFunc A custom equality function, to use instead of
     * {@link SortedArray.DefaultEqualityFunction}.
     *
     * @returns the newly constructed SortedArray, containing the given
     * values in sorted order.
     */
    static from<T>(values: Iterable<T> | ArrayLike<T>, compareFunc?: SortedArrayComparatorFunction<T>, equalityFunc?: SortedArrayEqualityFunction<T>): SortedArray<T>;
    /**
     * Construct a new SortedArray, initializing it with some values
     * in an iterable or array-like object that are already provided
     * in sorted order.
     *
     * @param values The values that should be inserted in the newly
     * constructed SortedArray. They must be sorted according to
     * the used comparator function, otherwise the returned SortedArray
     * may behave unexpectedly.
     * @param compareFunc A custom comparator function, to use instead of
     * {@link SortedArray.DefaultComparatorFunction}.
     * @param equalityFunc A custom equality function, to use instead of
     * {@link SortedArray.DefaultEqualityFunction}.
     *
     * @returns the newly constructed SortedArray, containing the given
     * assumed-sorted values.
     */
    static fromSorted<T>(values: Iterable<T> | ArrayLike<T>, compareFunc?: SortedArrayComparatorFunction<T>, equalityFunc?: SortedArrayEqualityFunction<T>): SortedArray<T>;
    /**
     * Insert a value into the array, maintaining sort order.
     *
     * You probably want to use this method instead of `push`.
     *
     * @param value The value to insert into the array.
     *
     * @returns the new length of the array.
     */
    insert(value: T): number;
    /**
     * Insert an iterable of assumed-sorted values into the array.
     *
     * This should typically be more efficient than calling
     * {@link SortedArray.insert} in a loop.
     *
     * @param values An iterable of values to be sorted into the
     * array, which are already sorted according to this SortedArray's
     * same comparator.
     *
     * @returns The new length of the array.
     *
     * @throws TypeError if the input was not iterable.
     */
    insertSorted(values: Iterable<T> | ArrayLike<T>): number;
    /**
     * Remove the first equal value from the array.
     *
     * Equality is determined using the SortedArray's equality function,
     * which is {@link SortedArray.DefaultEqualityFunction} when not
     * otherwise specified.
     *
     * @param value Remove the first item in the array that is equal
     * to this input value.
     *
     * @returns `true` if a matching element was found and removed,
     * or `false` if no matching element was found.
     */
    remove(value: T): boolean;
    /**
     * Remove the last equal value from the array.
     *
     * Equality is determined using the SortedArray's equality function,
     * which is {@link SortedArray.DefaultEqualityFunction} when not
     * otherwise specified.
     *
     * @param value Remove the last item in the array that is equal
     * to this input value.
     *
     * @returns `true` if a matching element was found and removed,
     * or `false` if no matching element was found.
     */
    removeLast(value: T): boolean;
    /**
     * Remove all equal values from the array.
     *
     * Equality is determined using the SortedArray's equality function,
     * which is {@link SortedArray.DefaultEqualityFunction} when not
     * otherwise specified.
     *
     * @param value Remove all items in the array that are equal
     * to this input value.
     *
     * @returns the number of removed array items.
     */
    removeAll(value: T): number;
    /**
     * Remove all equal values from the array and return those removed
     * values as a new SortedArray.
     *
     * Equality is determined using the SortedArray's equality function,
     * which is {@link SortedArray.DefaultEqualityFunction} when not
     * otherwise specified.
     *
     * @param value Remove the last item in the array that is equal
     * to this input value.
     *
     * @returns the removed elements as a new SortedArray.
     */
    getRemoveAll(value: T): SortedArray<T>;
    /**
     * Get all equal values in the array and return them as a new
     * SortedArray.
     *
     * Equality is determined using the SortedArray's equality function,
     * which is {@link SortedArray.DefaultEqualityFunction} when not
     * otherwise specified.
     *
     * @param value Return values in the array that are equal to this one.
     *
     * @returns the equivalent elements as a new SortedArray.
     */
    getEqualValues(value: T): SortedArray<T>;
    /**
     * Returns the first index at which a new value could be inserted
     * into the array and maintain its sort order.
     * This index will be before any other values with an equivalent sort
     * order, if there are any such values in the array.
     *
     * @param value The value to check for insertion index.
     * @param fromIndex Start comparing items at this index, inclusive.
     * Defaults to `0`, i.e. the beginning of the array.
     * @param endIndex Stop comparing items at this index, exclusive.
     * Defaults to the length of the array.
     *
     * @returns The first valid insertion index for a new value.
     */
    firstInsertionIndexOf(value: T, fromIndex?: number, endIndex?: number): number;
    /**
     * Returns the last index at which a new value could be inserted
     * into the array and maintain its sort order.
     * This index will be after any other values with an equivalent sort
     * order, if there are any such values in the array.
     *
     * @param value The value to check for insertion index.
     * @param fromIndex Start comparing items at this index, inclusive.
     * Defaults to `0`, i.e. the beginning of the array.
     * @param endIndex Stop comparing items at this index, exclusive.
     * Defaults to the length of the array.
     *
     * @returns The last valid insertion index for a new value.
     */
    lastInsertionIndexOf(value: T, fromIndex?: number, endIndex?: number): number;
    /**
     * Get the index of the first item in the array that is equal to
     * the given value, or `-1` if there is no equal item in the array.
     *
     * Equality is determined using the SortedArray's equality function,
     * which is {@link SortedArray.DefaultEqualityFunction} when not
     * otherwise specified.
     *
     * @param value Find the first index of a value in the array that
     * is equal to this one.
     * @param fromIndex Start looking for items at this index, inclusive.
     * Defaults to `0`, i.e. the beginning of the array.
     *
     * @returns the index of the first equal item, or `-1` if no equal
     * item was found.
     */
    indexOf(value: T, fromIndex?: number): number;
    /**
     * Get the index of the first item in the array that is equal to
     * the given value, or `-1` if there is no equal item in the array.
     *
     * Equality is determined using the SortedArray's equality function,
     * which is {@link SortedArray.DefaultEqualityFunction} when not
     * otherwise specified.
     *
     * @param value Find the first index of a value in the array that
     * is equal to this one.
     * @param fromIndex Start looking for items at this index, inclusive.
     * Defaults to `0`, i.e. the beginning of the array.
     * @param endIndex Stop looking for items at this index, exclusive.
     * Defaults to the length of the array.
     *
     * @returns the index of the first equal item, or `-1` if no equal
     * item was found.
     */
    indexOfRange(value: T, fromIndex?: number, endIndex?: number): number;
    /**
     * Get the index of the last item in the array that is equal to
     * the given value, or `-1` if there is no equal item in the array.
     *
     * Equality is determined using the SortedArray's equality function,
     * which is {@link SortedArray.DefaultEqualityFunction} when not
     * otherwise specified.
     *
     * Note that the behavior of this method differs from the normal
     * Array `lastIndexOf` method in that passing `undefined` explicitly
     * as the `endIndex` argument is treated the same as omitting that
     * argument, instead of coercing the value to `0`.
     *
     * @param value Find the last index of a value in the array that
     * is equal to this one.
     * @param endIndex Stop looking for items at this index.
     * Defaults to the end of the array.
     *
     * @returns the index of the last equal item, or `-1` if no equal
     * item was found.
     */
    lastIndexOf(value: T, endIndex?: number): number;
    /**
     * Get the index of the last item in the array that is equal to
     * the given value, or `-1` if there is no equal item in the array.
     *
     * Equality is determined using the SortedArray's equality function,
     * which is {@link SortedArray.DefaultEqualityFunction} when not
     * otherwise specified.
     *
     * @param value Find the last index of a value in the array that
     * is equal to this one.
     * @param fromIndex Start looking for items at this index, inclusive.
     * Defaults to `0`, i.e. the beginning of the array.
     * @param endIndex Stop looking for items at this index, exclusive.
     * Defaults to the length of the array.
     *
     * @returns the index of the last equal item, or `-1` if no equal
     * item was found.
     */
    lastIndexOfRange(value: T, fromIndex?: number, endIndex?: number): number;
    /**
     * Check whether any item in the array is equal to the given value.
     *
     * Equality is determined using the SortedArray's equality function,
     * which is {@link SortedArray.DefaultEqualityFunction} when not
     * otherwise specified.
     *
     * @param value Check whether there is any value in the array that
     * is equal to this one.
     * @param fromIndex Start looking for items at this index, inclusive.
     * Defaults to `0`, i.e. the beginning of the array.
     *
     * @returns `true` if an equal item was found in the array, or `false`
     * if not.
     */
    includes(value: T, fromIndex?: number): boolean;
    /**
     * Get a new SortedArray containing only those items which satisfy
     * a given predicate function.
     *
     * @params predicate A callback function which is invoked for each
     * item in the array. The returned array will contain only those
     * items for which the callback returned a truthy value.
     * @params thisArg An optional `this` argument which the predicate
     * function should be called with.
     *
     * @returns a new SortedArray containing only those values which
     * satisfied the predicate function.
     */
    filter<This = undefined>(predicate: SortedArrayElementCallback<This, T, unknown>, thisArg?: This): SortedArray<T>;
    /**
     * Reverse the items in the array, and update the array's comparator
     * function to account for this new reversed sort order.
     * Later insertions into this SortedArray will respect the reversed
     * sort order.
     *
     * @returns this SortedArray.
     */
    reverse(): this;
    /**
     * Get the items in the array from a start to an end index as a new
     * SortedArray.
     *
     * @param start Get items starting at this index, inclusive.
     * Defaults to `0`, i.e. the beginning of the array.
     * @param end Get items ending at this index, exclusive.
     * Defaults to the length of the array.
     *
     * @returns a new SortedArray containing the given array slice.
     */
    slice(start?: number, end?: number): SortedArray<T>;
    /**
     * Re-sort the array and assign a new comparator function.
     *
     * The array items will be sorted using the Array `sort` function.
     * This is not guaranteed to be stable in all cases. See:
     * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#sort_stability
     *
     * @param compareFunc The new comparator function to use for
     * this SortedArray.
     * Uses {@link SortedArray.DefaultComparatorFunction} by default,
     * if no comparator function is specified.
     *
     * @returns this SortedArray.
     */
    sort(compareFunc?: SortedArrayComparatorFunction<T>): this;
    /**
     * Forcibly re-sort the array using its previously assigned comparator
     * function. This might be used to repair the array, if its items are
     * no longer guaranteed to be in correct sorted order.
     *
     * The array items will be sorted using the Array `sort` function.
     * This is not guaranteed to be stable in all cases. See:
     * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#sort_stability
     *
     * @returns this SortedArray.
     */
    resort(): this;
    /**
     * Check whether the contents of the array are in fact sorted as
     * expected.
     *
     * @returns `true` when the contents of the array are correctly
     * sorted according to its comparator function, or `false` otherwise.
     */
    isSorted(): boolean;
    /**
     * Remove items from the array, starting at a given index.
     *
     * @param start Start removing items from the array at this index.
     * @param deleteCount The number of items that should be removed.
     *
     * @returns A new SortedArray containing the removed items.
     */
    splice(start: number, deleteCount?: number): SortedArray<T>;
    /**
     * Remove items from the array, starting at a given index, and
     * insert new items at that index.
     *
     * **Warning:** If inserting the provided `items` would invalidate
     * the implementation's assumptions about array items being in sorted
     * order, then the implementation will behave in unexpected ways.
     * Use this method with caution.
     *
     * @param start Start removing items from the array at this index.
     * @param deleteCount The number of items that should be removed.
     * @param items A list of items which should be newly inserted in place
     * of the removed items. The implementation assumes that these items
     * can be inserted without violating the sort order of the SortedArray.
     *
     * @returns A new SortedArray containing the removed items.
     */
    splice(start: number, deleteCount: number, ...items: T[]): SortedArray<T>;
    /**
     * Get a new array with the values in this array concatenated with
     * any number of other arrays.
     *
     * This method is overridden to ensure that a normal Array is returned,
     * instead of a SortedArray. It does not otherwise change the method's
     * behavior.
     *
     * @param items Arrays to concatenate.
     *
     * @returns a new array containing the concatenated items.
     */
    concat(...items: (T | ConcatArray<T>)[]): T[];
    /**
     * Get a new array with sub-array items concatenated into it
     * recursively, up to the specified depth.
     *
     * This method is overridden to ensure that a normal Array is returned,
     * instead of a SortedArray. It does not otherwise change the method's
     * behavior.
     *
     * @param depth How deep a nested array structure should be flattened.
     * Defaults to `1`.
     *
     * @returns a new array containing the flattened items.
     */
    flat<This, Depth extends number = 1>(this: This, depth?: Depth): FlatArray<This, Depth>[];
    /**
     * Get a new array formed by applying a given transformation callback
     * function to each item in the array, and then flattening the result
     * by one level.
     *
     * This method is overridden to ensure that a normal Array is returned,
     * instead of a SortedArray. It does not otherwise change the method's
     * behavior.
     *
     * @param transform A transformation callback function to be invoked
     * for each item in the array. It should return an array containing new
     * items for the new array, or a single non-array value to be added to
     * the new array.
     *
     * @returns a new array containing the mapped and flattened items.
     */
    flatMap<U, This = undefined>(transform: SortedArrayElementCallback<This, T, U | ReadonlyArray<U>>, thisArg?: This): U[];
    /**
     * Get a new array populated with the results of calling a transformation
     * callback function on every item in this array.
     *
     * This method is overridden to ensure that a normal Array is returned,
     * instead of a SortedArray. It does not otherwise change the method's
     * behavior.
     *
     * @param transform A transformation callback function to be invoked
     * for each item in the array. Its return value is added as a single
     * item in the new array.
     *
     * @returns a new array containing the values returned by calls to
     * the transformation function.
     */
    map<U, This = undefined>(transform: SortedArrayElementCallback<This, T, U>, thisArg?: This): U[];
}
export declare namespace SortedArray {
    /**
     * Type of an equality function that can be used in constructing and
     * configuring a {@link SortedArray} instance.
     *
     * Equality functions accept two inputs and return a truthy value
     * when they are identical a falsey value when they are not.
     *
     * See also {@link SortedArray.DefaultEqualityFunction}.
     * This is the default function that is used for a {@link SortedArray}
     * when none is explicitly provided.
     */
    type EqualityFunction<T> = SortedArrayEqualityFunction<T>;
    /**
     * Type of a comparison function that can be used in constructing and
     * configuring a {@link SortedArray} instance.
     *
     * Comparator functions accept two inputs and return a negative number
     * when the first argument comes before the second argumet in a sorted
     * order, a positive number when the first argument comes after the
     * second, and zero when they have same sort order.
     *
     * See also {@link SortedArray.DefaultComparatorFunction}.
     * This is the default function that is used for a {@link SortedArray}
     * when none is explicitly provided.
     */
    type ComparatorFunction<T> = SortedArrayComparatorFunction<T>;
    /**
     * Default equality function used by {@link SortedArray} instances,
     * when no other function was provided.
     *
     * The default equality function uses `SameValueZero` comparison,
     * i.e. strict equality using the `===` triple equals operator.
     *
     * See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness
     */
    const DefaultEqualityFunction: SortedArrayEqualityFunction<unknown>;
    /**
     * Default comparator function used by {@link SortedArray} instances,
     * when no other function was provided.
     *
     * The default comparator function returns `-1` when `a < b`,
     * `+1` when `a > b`, and `0` otherwise.
     */
    const DefaultComparatorFunction: SortedArrayComparatorFunction<unknown>;
    /**
     * Generic callback type used by some {@link SortedArray} methods.
     */
    type ElementCallback<This, T, U> = SortedArrayElementCallback<This, T, U>;
}
export default SortedArray;