@eclipse-glsp/protocol/lib/utils/array-util.d.ts

The protocol definition for client-server communication in GLSP

/********************************************************************************
 * Copyright (c) 2019-2024 EclipseSource and others.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the Eclipse
 * Public License v. 2.0 are satisfied: GNU General Public License, version 2
 * with the GNU Classpath Exception which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 ********************************************************************************/
import { Constructor, Primitive, TypeGuard } from './type-util';
/**
 * A union type for for objects that can either be a single element or and array of elements.
 */
export type MaybeArray<T> = T | T[];
/**
 * Returns the first element of the given array.
 * @param array the array.
 * @returns the element at index 0.
 */
export declare function first<T>(array: T[]): T;
/**
 * Returns the first n elements of the given array.
 * @param array The array.
 * @param n The number of elements that should be returned
 * @returns The first n elements of the array
 */
export declare function first<T>(array: T[], n: number): T[];
/**
 * Returns the last element of the given array.
 * @param array The array.
 * @returns The last element in the array.
 */
export declare function last<T>(array: T[]): T;
/**
 * Returns the last n elements of the given array.
 * @param array The array.
 * @param n The number of elements that should be returned
 * @returns The last n elements of the array
 */
export declare function last<T>(array: T[], n: number): T[];
/**
 * Plucks (i.e. extracts) the property value that corresponds to the given key from all objects of the array.
 * @param array The array which should be plucked.
 * @param key  The key of the property that should be extracted.
 * @returns A new array containing the plugged property for each element of the array.
 */
export declare function pluck<T, K extends keyof T>(array: T[], key: K): Array<T[K]>;
/**
 * Removes the given values from the given array (if present).
 * @param array The array to execute the remove operation on.
 * @param values The values that should be removed from the array.
 */
export declare function remove<T>(array: T[], ...values: T[]): void;
/**
 * Push an array of values to the given array. The values can either be single objects of a concrete type `T`
 * or can also be nested arrays of T. If nested arrays are passed the they will be destructured (i.e. flattened)
 * so that they can be pushed to the given array.
 * @param array The array to push to.
 * @param toPush The values of {@link MaybeArray}s that should be pushed.
 */
export declare function flatPush<T>(array: T[], toPush: MaybeArray<T>[]): void;
/**
 * Helper function to convert a {@link MaybeArray} into an array.
 * @param maybe The MaybeArray to convert
 * @returns The corresponding array
 */
export declare function asArray<T>(maybe: MaybeArray<T>): T[];
/**
 * Adds the given values to the given array. The add operation is executed distinct meaning
 * a value will not be pushed to the array if its already present in the array.
 * @param array The array to push to.
 * @param values The values that should be added distinctively.
 */
export declare function distinctAdd<T>(array: T[], ...values: T[]): void;
/**
 * A typeguard function to check wether a given object is an array of a specific type `T`. As it checks the type of each individual
 * array element this guard check is expensive and should only be used in cases where complete type-safety is required.
 * @param object The object to check.
 * @param typeGuard A typeguard to check the type of the individual elements.
 * @param supportEmpty A flag to determine wether empty arrays should pass the typeguard check.
 * @returns A type predicate indicating wether the given object has passed the type guard check.
 */
export declare function isArrayOfType<T>(object: unknown, typeGuard: (elem: unknown) => elem is T, supportEmpty?: boolean): object is T[];
/**
 * A typeguard function to check wether a given object is an array of a class`T`. As it checks the wether each individual element
 * is an instance of the given class this  guard check is expensive and should only be used in cases where complete type-safety is required.
 * @param object The object to check.
 * @param constructor The constructor for the class under test.
 * @param supportEmpty A flag to determine wether empty arrays should pass the typeguard check.
 * @returns A type predicate indicating wether the given object has passed the type guard check.
 */
export declare function isArrayOfClass<T>(object: unknown, constructor: Constructor<T>, supportEmpty?: boolean): object is T[];
/**
 * A typeguard function to check wether a given object is an array of a {@link PrimitiveType} `T. As it checks the type of each individual
 * array element this guard check is expensive and should only be used in cases where complete type-safety is required.
 * @param object The object to check.
 * @param primitiveType The expected primitive type of the elements.
 * @param supportEmpty A flag to determine wether empty arrays should pass the typeguard check.
 * @returns A type predicate indicating wether the given object has passed the type guard check.
 */
export declare function isArrayOfPrimitive<T>(object: unknown, primitiveType: Primitive, supportEmpty?: boolean): object is T[];
/**
 * A typeguard function to check wether a given object is an array of a strings. As it checks the type of each individual
 * array element this guard check is expensive and should only be used in cases where complete type-safety is required.
 * @param object The object to check.
 * @param supportEmpty A flag to determine wether empty arrays should pass the typeguard check.
 * @returns A type predicate indicating wether the given object has passed the type guard check.
 */
export declare function isStringArray(object: unknown, supportEmpty?: boolean): object is string[];
/**
 * A typeguard function to check wether a given object is an array where each element matches the given predicate.
 * @param object The object to check.
 * @param predicate The predicate to test with.
 * @param supportEmpty A flag to determine wether empty arrays be matched by the predicate..
 * @returns `true` if the given object is an array and all elements match the given predicate. `false` otherwise.
 */
export declare function isArrayMatching(object: unknown, predicate: (elem: unknown) => boolean, supportEmpty?: boolean): boolean;
export declare function partition<T>(source: T[], matchGuard: TypeGuard<T>): {
    match: T[];
    rest: T[];
};
/**
 * Helper function to create an array of values without any undefined values.
 * @param values The values to create the array from.
 * @returns The array of values without any undefined values.
 */
export declare function arrayOf<T>(...values: (T | undefined)[]): T[];
//# sourceMappingURL=array-util.d.ts.map