@eclipse-scout/core/dist/d.ts/src/util/objects.d.ts

Eclipse Scout runtime

import { Primitive } from '../index';
export declare const objects: {
    /**
     * Uses Object.create(null) to create an object without a prototype. This is different to use the literal {} which links the object to Object.prototype.
     * <p>
     * Not using the literal has the advantage that the object does not contain any inherited properties like `toString` so it is not necessary to use `o.hasOwnProperty(p)`
     * instead of `p in o` to check for the existence.
     *
     * @param [properties] optional initial properties to be set on the new created object
     */
    createMap(properties?: object): any;
    /**
     * Copies all the properties (including the ones from the prototype.) from dest to source
     * @param [filter] an array of property names.
     * @returns the destination object (the destination parameter will be modified as well)
     */
    copyProperties<D>(source: object, dest: D, filter?: string[] | string): D;
    /**
     * Creates a dynamic proxy which can be used e.g. to initialize a constant.
     * The proxy wraps an instance created on first use using the given constructor function.
     * All calls to the proxy are forwarded to this lazy instance.
     * The instance can only be created after the {@link ObjectFactory} has been initialized.
     * @param constr The constructor to lazily create the instance on first use.
     * @returns A proxy that delegates calls to the lazy instance.
     */
    createSingletonProxy<T extends object>(constr: new () => T): T;
    /**
     * Copies the own properties (excluding the ones from the prototype) from source to dest.
     * If a filter is specified, only the properties matching the ones in the filter are copied.
     * @param [filter] an array of property names.
     * @returns the destination object (the destination parameter will be modified as well)
     */
    copyOwnProperties<D_1>(source: object, dest: D_1, filter?: string[] | string): D_1;
    /**
     * Counts and returns the properties of a given object or map (see #createMap).
     */
    countOwnProperties(obj: object): number;
    /**
     * Copies the specified properties (including the ones from the prototype) from source to dest.
     * Properties that already exist on dest are NOT overwritten.
     */
    extractProperties<D_2>(source: object, dest: D_2, properties: string[]): D_2;
    /**
     * returns
     *  - true if the obj has at least one of the given properties.
     *  - false if the obj has none of the given properties.
     */
    someOwnProperties(obj: object, properties: string[] | string): boolean;
    /**
     * returns
     *  - true if the obj or its prototypes have at least one of the given properties.
     *  - false if the obj or its prototypes have none of the given properties.
     */
    someProperties(obj: object, properties: string[] | string): boolean;
    /**
     * Creates a copy of the given object with the properties in alphabetic order. The characters in the property names are compared
     * individually (no alphanumeric sorting). The names are first sorted by ascending length and then by character class: special
     * characters (punctuation etc.), then numbers (0-9), then lowercase letters (a-z), then uppercase letters (A-Z).
     *
     * The order of elements in an array is preserved. Values that are not plain objects are left as is. This method detects cyclic
     * references and does not throw an error. Instead, the cyclic reference is reassigned to the corresponding copy.
     *
     * @param recursive whether to recursively sort property names in nested objects. The default value is `true`.
     */
    sortProperties<T_1>(obj: T_1, recursive?: boolean): T_1;
    /**
     * Creates deep clones of given value.
     * The following types are supported:
     * * Pojo
     * * `Array`
     * * `Date`
     * * `Map`
     * * `Set`
     * * All objects (except Widget) having a `clone` function (expected to create a deep clone without taking any arguments). These are classes like `BaseDoEntity`, `Dimension`, `GridData`, `Insets`, `Point`, `Status`, `URL`, ...
     * @param val The value to deep clone.
     * @returns The deep clone if supported, the input value otherwise.
     */
    valueCopy<T_2>(val: T_2): T_2;
    /**
     * Returns the first object with the given property and propertyValue or null if there is no such object within parentObj.
     * @param property property to search for
     * @param propertyValue value of the property
     */
    findChildObjectByKey(parentObj: any, property: string, propertyValue: any): any;
    /**
     * This function returns the value of a property from the provided object specified by the second path parameter.
     * The path consists of a dot separated series of property names (e.g. foo, foo.bar, foo.bar.baz).
     * In addition, traversing into array properties is possible by specifying a suitable filter for the element's id property in square brackets (e.g. foo[bar], foo.bar[baz]).
     *
     * Example:
     *
     * let obj = {
     *   foo: {
     *     bar: {
     *       foobar: 'val1'
     *     }
     *   },
     *   baz: [
     *     {
     *       id: 'baz1',
     *       value: 'val2'
     *     },
     *     {
     *       id: 'baz2',
     *       value: 'val3'
     *     }
     *   ]
     * }
     *
     * objects.getByPath(obj, 'foo') === obj.foo;
     * objects.getByPath(obj, 'foo.bar') === obj.foo.bar;
     * objects.getByPath(obj, 'baz[baz1]') → { id: 'baz1', value: 'val2' }
     * objects.getByPath(obj, 'baz[baz2].value') → 'val3'
     *
     * @param object The object to select a property from.
     * @param path The path for the selection.
     * @returns Object Returns the selected object.
     * @throws Throws an error, if the provided parameters are malformed, or a property could not be found/a id property filter does not find any elements.
     */
    getByPath(object: object, path: string): any;
    /**
     * @deprecated The method was renamed to {@link isObject}. Use the new name or consider using {@link isPojo} instead.
     */
    isPlainObject<T_3>(obj: T_3): obj is Exclude<T_3, Primitive | T_3[]>;
    /**
     * @returns true if the given object is an object: no primitive type (number, string, boolean, bigint, symbol), no array, not null and not undefined.
     */
    isObject<T_4>(obj: T_4): obj is Exclude<T_4, Primitive | T_4[]>;
    /**
     * Checks if the given object is a plain old JavaScript object, which is an object created by the object literal notation (`{}`), `Object.create` or `new Object()`.
     *
     * Note: objects without prototype (e.g. created using `Object.create(null)` or {@link objects.createMap}) return true here.
     * So methods typically <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#instance_methods">inherited from Object</a> may not be available for a pojo!
     * @returns true if it is a pojo, false otherwise.
     */
    isPojo<T_5>(obj: T_5): obj is Exclude<T_5, Primitive | T_5[]>;
    /**
     * Null-safe access the property of objects. Instead of using this function consider using conditional chaining with the elvis operator: obj?.foo?.bar.
     * Examples:
     * <ul>
     * <li><code>optProperty(obj, 'value');</code> try to access and return obj.value</li>
     * <li><code>optProperty(obj, 'foo', 'bar');</code> try to access and return obj.foo.bar</li>
     * </ul>
     *
     * @returns the value of the requested property or undefined if the property does not exist on the object
     */
    optProperty(obj: object, ...properties: string[]): any;
    /**
     * Returns true if:
     * - obj is not undefined or null
     * - obj not isNaN
     * - obj isFinite
     *
     * This method is handy in cases where you want to check if a number is set. Since you cannot write:
     *   if (myNumber) { ...
     *
     * Because when myNumber === 0 would also resolve to false. In that case use instead:
     *   if (isNumber(myNumber)) { ...
     */
    isNumber(obj: any): obj is number;
    isString(obj: any): obj is string;
    isNullOrUndefined(obj: any): obj is null;
    isFunction(obj: any): obj is Function;
    /**
     * Returns true if the given object is {@link isNullOrUndefined null or undefined} or {@link isEmpty empty}.
     */
    isNullOrUndefinedOrEmpty(obj: any): boolean;
    isArray(obj: any): obj is any[];
    /**
     * Checks whether the provided value is a promise or not.
     * @param value The value to check.
     * @returns true, in case the provided value is a thenable, false otherwise.
     *
     * Note: This method checks whether the provided value is a "thenable" (see https://promisesaplus.com/#terminology).
     *       Checking for promise would require to check the behavior which is not possible. So you could provide an object
     *       with a "then" function that does not conform to the Promises/A+ spec but this method would still return true.
     */
    isPromise(value: any): value is PromiseLike<any>;
    /**
     * Returns values from the given (map) object. By default, only values of 'own' properties are returned.
     *
     * @param obj
     * @param all can be set to true to return all properties instead of own properties
     * @returns an Array with values
     */
    values<K extends PropertyKey, V>(obj: Record<K, V>, all?: boolean): V[];
    /**
     * @returns the key (name) of a property with given value
     */
    keyByValue<V_1>(obj: Record<string, V_1>, value: V_1): string;
    /**
     * Java-like equals method.
     *
     * The two values are considered equal if one of the following rules applies:
     *
     * * They are the same objects (===).
     * * They are Dates having the same value.
     * * They are both zero-length collections (Array, Map or Set).
     * * They have both an `equals` method, are of the same Class type and this `equals` method returns `true`.
     *
     * @returns true if both values are equal.
     */
    equals(objA: any, objB: any): boolean;
    /**
     * Compares two objects and all its child elements recursively using value equality as defined by {@link #equals}. Order of the property keys is ignored.
     *
     * @param objA The first value to compare.
     * @param objB The second value to compare.
     * @param skipRootEquals An optional boolean indicating if the equals method should be ignored for the given two objects. Default is false.
     * It might be handy to set this to true if it is called from within an equals method to prevent stack overflows.
     * @returns true if both objects and all child elements are equals by value or implemented equals method.
     * @see objects.equals
     */
    equalsRecursive(objA: any, objB: any, skipRootEquals?: boolean): boolean;
    /**
     * Compares a list of properties of two objects by using the equals method for each property.
     */
    propertiesEquals(objA: object, objB: object, properties: string[]): boolean;
    /**
     * @returns the function identified by funcName from the given object. The function will return an error
     *     if that function does not exist. Use this function if you modify an existing framework function
     *     to find problems after refactoring / renaming as soon as possible.
     */
    mandatoryFunction(obj: object, funcName: string): Function;
    /**
     * Use this method to replace a function on a prototype of an object. It checks if that function exists
     * by calling <code>mandatoryFunction</code>.
     */
    replacePrototypeFunction(obj: any, funcOrName: string | ((...args) => any), func: Function, rememberOrig: boolean): void;
    /**
     * @returns a real Array for the pseudo-array 'arguments'.
     */
    argumentsToArray(args: IArguments): any[];
    /**
     * Used to loop over 'arguments' pseudo-array with forEach.
     */
    forEachArgument(args: IArguments, func: (value: any, index: number, args: any[]) => void): void;
    /**
     * @param value text which contains a constant reference like '${const:FormField.LabelPosition.RIGHT}'.
     * @returns the resolved constant value or the unchanged input value if the constant could not be resolved.
     */
    resolveConst(value: string, constType?: any): any;
    resolveConstProperty(object: object, config: {
        property: string;
        constType: any;
    }): void;
    resolveConstProperties(object: object, configs: {
        property: string;
        constType: any;
    }[]): void;
    /**
     * Cleans the given object, i.e. removes all top-level properties with values that are null, undefined or
     * consist of an empty array or an empty object. This is useful to have a minimal data object.
     *
     * This method is *not* recursive.
     *
     * The object is modified *in-place* and is also returned.
     *
     * If the given object is set but not a {@link isObject plain object}, an error is thrown.
     *
     * @see isNullOrUndefinedOrEmpty
     */
    removeEmptyProperties(object: any): any;
    /**
     * Empty if the argument is:
     * - `null`
     * - `undefined`
     * - an empty {@link Array}
     * - an empty {@link Map}
     * - an empty {@link Set}
     * - or an object without keys (except {@link Date} which is never empty).
     *
     * @returns `true` if *obj* is empty, `false` if *obj* is not empty, `undefined` if *obj* is no object (e.g. a primitive).
     */
    isEmpty(obj: any): boolean | undefined;
    /**
     * @returns true if the first parameter is the same or a subclass of the second parameter.
     */
    isSameOrExtendsClass<TClass2>(class1: any, class2: abstract new () => TClass2): class1 is new () => TClass2;
    /**
     * Converts any non-string argument to a string that can be used as an object property name.
     * Complex objects are converted to their JSON representation (instead of returning something
     * non-descriptive such as '[Object object]').
     */
    ensureValidKey(key: any): string;
    /**
     * Receives the value for the given key from the map, if the value is not null or undefined.
     * If the key has no value associated, the value will be computed with the given function and added to the map, unless it is null or undefined.
     *
     * @returns the value associated with the given key or the computed value returned by the given mapping function.
     */
    getOrSetIfAbsent<TKey, TValue>(map: Map<TKey, TValue>, key: TKey, computeValue: (key: TKey) => TValue): TValue;
    /**
     * Compares two Sets for equality using {@link equals}.
     *
     * @param setA First Set.
     * @param setB Second Set.
     * @param deep Specifies if a deep comparison should be performed (recursively). If the Set value is a non-primitive type the equals steps into these structures (Objects, Arrays, Maps, Sets). Default is false.
     */
    equalsSet(setA: Set<any>, setB: Set<any>, deep?: boolean): boolean;
    /**
     * Compares two Maps for equality using {@link equals} on keys and values.
     *
     * @param setA First Map.
     * @param setB Second Map.
     * @param deep Specifies if a deep comparison should be performed (recursively). If the Map key or value is a non-primitive type the equals steps into these structures (Objects, Arrays, Maps, Sets). Default is false.
     */
    equalsMap(mapA: Map<any, any>, mapB: Map<any, any>, deep?: boolean): boolean;
};
//# sourceMappingURL=objects.d.ts.map