@cute-dw/core
Version:
This TypeScript library is the main part of a more powerfull package designed for the fast WEB software development. The cornerstone of the library is the **DataStore** class, which might be useful when you need a full control of the data, but do not need
359 lines (358 loc) • 13.8 kB
TypeScript
import { Supplier } from "./function/Supplier";
import { Class } from "./interface/Class";
import { Cloneable } from "./interface/Cloneable";
/**
* This class consists of the static utility methods for operating on objects, or checking certain conditions before operation
*/
export declare class Objects {
/**
* Returns a string presentation of any JavaScript object
* @static
* @param value JavaScript object/value of any type
* @returns String in the following format: [object \<type\>]
*/
static toString(value: any): string;
/**
* Returns a first not _nullable_ value from the specified `values`
* @param values An array or list of values to check
* @returns A first not _nullable_ value in the `values` array if any, or _null_ if else.
*/
static coalesce(...values: any[]): any;
/**
*
* @param v1
* @param v2
* @returns
*/
static ifNull(v1: any, v2: any): any;
static ifUndefined(v1: any, v2: any): any;
static ifEmpty(v1: any, v2: any): any;
static ifNotArray(v1: any, v2: any): any;
static nullIf(v1: any, v2: any): any;
static isArray(value: any): value is Array<any>;
static isBoolean(value: any): value is Boolean;
static isCloneable(value: any): value is Cloneable;
static isDate(value: any): value is Date;
static isIterable(value: any): value is Iterable<any>;
static isMap(value: any): value is Map<any, any>;
static isNull(value: any): value is null;
static isNumber(value: any): value is number;
static isSet(value: any): value is Set<any>;
static isString(value: any): value is String;
static isUndefined(value: any): value is undefined;
/**
* Check if specified value is empty (falsy)
* @static
* @param {any} value Any value to check
* @returns {boolean} true/false
*/
static isEmpty(value: any): boolean;
/**
* Return whether the provided value is a function.
*
* @static
* @param {*} value The value to test.
* @returns {boolean} Whether the provided value is a function.
* @since 1.0.0
* @example
* const a = function () { console.log('foo bar'); };
* const b = { foo: "bar" };
* console.log(Objects.isFunction(a)); // true
* console.log(Objects.isFunction(b)); // false
*/
static isFunction(value: any): value is Function;
static isNumberObject(value: any): value is Number;
/**
* Return whether the provided value is an object.
*
* @static
* @param {*} value The value to test.
* @returns {boolean} Whether the provided value is an object.
* @since 1.0.0
*
* @example
* const a = { foo: "bar" };
* const b = 'foo bar';
* console.log(Objects.isObject(a)); // true
* console.log(Objects.isObject(b)); // false
*/
static isObject(value: any): value is Object;
static isPlainObject(value: any): value is Object;
static isPrimitive(arg: any): boolean;
/**
* Objects casting with runtime checkings
* @param obj Object to cast
* @param AnyClass Target class value or type
* @returns Object of type `AnyClass` if succeeds, or _undefined_ if the `obj` is not the `AnyClass`' instance
* @example
* // %inferred-type: any
* const parsed = JSON.parse( someJsonObjectString );
* const p: Person = Objects.cast(parsed, Person);
*/
static cast<T>(obj: any, AnyClass: Class<T>): T | undefined;
/**
* Creates an instance of the JavaScript's class value
* @static
* @param AnyClass Class value
* @param args Constructor arguments
* @returns The instance of the class
* @example
* class Person {
* constructor(public name: string) {}
* }
* // %inferred-type: Person
* const jane = Objects.createInstance(Person, 'Jane');
*/
static createInstance<T>(AnyClass: Class<T>, ...args: any[]): T;
/**
* Returns constructor object of the specified value/object. If the `value` is _null_ or _undefined_, method returns constructor of an empty object
* @param value An object for which the class object to return
* @returns Returns constructor object
* @static
* @see {@link getClassName}
*/
static getClass(value: Object): Function;
/**
* Returns class name of the specified value/object
* @param value A value for which the class name to return
* @returns The name of the JavaScript class to which the `value` belongs
* @static
* @see {@link getClass}
*/
static getClassName(value: any): string;
/**
* Tests to see if the prototype property of a constructor appears anywhere in the prototype chain of an object
* @param value The object to test
* @param ctor Constructor or a name of the class to test against
* @returns Boolean value
* @static
*/
static isInstanceOf(value: Object, ctor: Class<unknown> | string): boolean;
/**
* Checks that the specified object reference is not null and throws a customized `NullPointerException` if it is
* @param obj The object reference to check for nullity
* @param message Detail message to be used in the event that a `NullPointerException` is thrown
* @returns `obj` if not null or undefined
* @throws NullPointerException if `obj` is null
* @static
*/
static requireNonNull(obj: any, message?: string | Supplier<string>): any;
private static _isPrototypePolluted;
/**
* Returns objects's property value using property's path in hierarchical structure of the object
*
* @static
* @param object Source object
* @param path Path to property point ('.') delimited
* @param defValue Optional default value
* @returns Value of property or undefined if it was not found in object's structure
*
* @example
* let obj = {a:1, b:{c:2, d:3, f:[10,20,30,[{s:100}]]}};
* console.log(Objects.getValue(obj, "b.c.d")); // undefined
* console.log(Objects.getValue(obj, "b.f.3.0.s")); // 100
*/
static getValue(object: any, path: string, defValue?: any): any;
/**
* Checks existance a path to the property in the specified object
* @static
* @param object Object to check
* @param path Path to the object's property dot (".") delimited
* @returns _true_ if the path is a valid path to the some property in the `object`, _false_ otherwise
*/
static hasValue(object: any, path: string): boolean;
/**
* Sets value of object property using its path in the object's structure
* @static
* @param object Target object
* @param path String path delimited by dot (".")
* @param newValue New value for the property if it will be found in the object's structure
* @param force Optional. Enforce to create the full `path` in the `object` structure if it doesn't exist. Default is _false_.
* @returns 1 if it succeeds and -1 if an error occurs
*/
static setValue(object: any, path: string, newValue: any, force?: boolean): number;
/**
* Return whether `prop` is matched by any string or regular expression in
* `blacklist`.
*
* @static
* @param {string} prop The name of a property to check.
* @param {array} blacklist Array of strings and regular expressions.
* @returns {boolean} Whether `prop` was matched.
* @since 1.0.0
* @example
* const blacklist = [/^\$hashKey/g, /^_/g, 'id'];
* console.log(Objects.isBlacklisted("$hashKey", blacklist)); // true
* console.log(Objects.isBlacklisted("id", blacklist)); // true
* console.log(Objects.isBlacklisted("_myProp", blacklist)); // true
* console.log(Objects.isBlacklisted("my_id", blacklist)); // false
*/
static isBlacklisted(prop: string, blacklist: any[]): boolean;
/**
* Iterate over an object's own enumerable properties.
*
* @static
* @param {object} object The object whose properties are to be enumerated.
* @param {Function} fn Iteration function.
* @param {object} [thisArg] Content to which to bind `fn`.
* @since 1.0.0
* @example
* const a = { b: 1, c: 4 };
* let sum = 0;
* Objects.forOwn(a, function (value, key) {
* sum += value;
* });
* console.log(sum); // 5
*/
static forOwn(object: Object, fn: Function, thisArg?: any): void;
/**
* Shallow copy own enumerable properties from `src` to `dest` that are on
* `src` but are missing from `dest.
*
* @static
* @param {object} dest The destination object.
* @param {object} source The source object.
* @returns {object} The destination object.
* @since 1.0.0
*
* @example
* const a = { foo: 'bar', beep: 'boop' };
* const b = { beep: 'bip' };
* Objects.fillIn(b, a);
* console.log(b); // {"foo":"bar","beep":"bip"}
*/
static fillIn(dest: any, ...source: any): any;
/**
* Recursively shallow fill in own enumerable properties from `source` to `dest`.
*
* @static
* @param {object} dest The destination object.
* @param {object} source The source object.
* @returns {object} The destination object.
* @see {@link fillIn}
* @see {@link deepMixIn}
* @since 1.0.0
*
* @example
* const a = { foo: { bar: 'baz' }, beep: 'boop' };
* const b = { beep: 'bip' }
* Objects.deepFillIn(b, a);
* console.log(b); // {"foo":{"bar":"baz"},"beep":"bip"}
*/
static deepFillIn(dest: any, source: any): any;
/**
* Recursively shallow copy enumerable properties from `source` to `dest`.
*
* @static
* @param {object} dest The destination object.
* @param {object} source The source object.
* @since 1.0.0
*
* @example
* const a = { foo: { bar: 'baz' }, beep: 'boop' };
* const b = { beep: 'bip' };
* Objects.deepMixIn(b, a);
* console.log(b); // {"foo":{"bar":"baz"},"beep":"boop"}
*/
static deepMixIn(dest: any, source: any): any;
/**
* Return whether the two values are the same value
*
* @static
* @param {*} a The first value to compare
* @param {*} b The second value to compare
* @returns {boolean} A boolean indicating whether or not the two arguments are the same value
* @see {@link deepEqual}
* @since 1.0.0
*
* @example
* console.log( Objects.equals(1, 1) ); // true
* console.log( Objects.equals(1,'1') ); // false
* console.log( Objects.equals(93, 66) ); // false
*/
static equals(a: any, b: any): boolean;
/**
* Check whether the two provided objects are deeply equal.
*
* @static
* @param {object} a First object in the comparison.
* @param {object} b Second object in the comparison.
* @returns {boolean} Whether the two provided objects are deeply equal.
* @see {@link equal}
* @since 1.0.0
*
* @example
* const objA = {
* name: 'John',
* id: 27,
* nested: {
* item: 'item 1',
* colors: ['red', 'green', 'blue']
* }
* };
*
* const objB = {
* name: 'John',
* id: 27,
* nested: {
* item: 'item 1',
* colors: ['red', 'green', 'blue']
* }
* };
*
* console.log(Objects.deepEqual(a,b)); // true
* objB.nested.colors.add('yellow'); // make a change to a nested object's array
* console.log(Objects.deepEqual(a,b)); // false
*/
static deepEqual(a: any, b: any): boolean;
/**
* Return a diff of the base object to the comparison object.
*
* @static
* @param {object} newObject Comparison object.
* @param {object} oldObject Base object.
* @param {object} [opts] Configuration options.
* @returns {Object} The diff from the base object to the comparison object.
* @see {@link areDifferent}
* @since 1.0.0
*
* @example
* const oldObject = { foo: 'bar', a: 1234 };
* const newObject = { beep: 'boop', a: 5678 };
* const diff = Objects.diffObjects.(oldObject, newObject);
* console.log(diff.added); // {"beep":"boop"}
* console.log(diff.changed); // {"a":5678}
* console.log(diff.removed); // {"foo":undefined}
*/
static diffObjects(newObject: any, oldObject: any, opts?: {
equalsFn?: Function;
ignore?: any[];
}): any;
/**
* Return whether the two objects are deeply different.
*
* @static
* @param {object} newObject Base object.
* @param {object} oldObject Comparison object.
* @param {object} [opts] Configuration options.
* @returns {boolean} Whether the two objects are deeply different.
* @see {@link diffObjects}
* @since 1.0.0
*
* @example
* Objects.areDifferent({}, {}); // false
* Objects.areDifferent({ a: 1 }, { a: 1 }); // false
* Objects.areDifferent({ foo: 'bar' }, {}); // true
*/
static areDifferent(newObject: any, oldObject: any, opts: any): boolean;
/**
* Deep cloning of the specified object. If the `source` object implements
* `Cloneable` interface its `clone` method is executed.
*
* @static
* @param {object} source Source object to clone
* @returns {object} Cloned object.
* @since 1.0.0
*/
static deepClone(source: any): any;
}