util - Utilities

老猫10/22/22About 4 min

The util module is implemented to align with the early Node.js util module. For easier Java interop, it also provides the $util.java object.

$util.java

Provides helper utilities for Java interop.

$util.java.instanceOf(obj, clazz)

obj {any} Java object
clazz {string} Class name
Returns {boolean}

Check whether an object is an instance of the specified class. Returns true if yes; otherwise false.

$util.java.array(type, size)

type {string} Array type. It can be a Java class name, or one of the following primitive types:
- "int"
- "long"
- "double"
- "char"
- "byte"
- "float"
size {number} Array size
Returns {Java array}

Create and return a Java array. For example, create a byte array: let bytes = $util.java.array('byte', 1024).

$util.java.toJsArray(list, nullListToEmptyArray)

list {List} A java.util.List object
nullListToEmptyArray {boolean} Convert null list to empty array or not
Returns {Array}

Convert a Java List to a JavaScript array.

$util.java.objectToMap(obj)

obj {any} Object
Returns {java.util.Map}

Convert a JavaScript object to a java.util.Map.

$util.java.mapToObject

map {Map} Java Map object
Returns {obj}

Convert a java.util.Map to a JavaScript object.

$util.format(format[, ...args])

format {string} A printf-like format string.

$util.format() returns a formatted string using a printf-like format.

The first argument is a string containing zero or more placeholder tokens. Each placeholder is replaced by the corresponding argument. Supported placeholders:

%s - String.
%d - Number (integer or float).
%i - Integer.
%f - Float.
%j - JSON. If the argument contains circular references, it will be replaced with the string '[Circular]'.
%o - Object. Generic JavaScript object formatting, similar to $util.inspect() with options \{ showHidden: true, depth: 4, showProxy: true \}. This shows the full object including non-enumerable symbols and properties.
%O - Object. Generic JavaScript object formatting, similar to $util.inspect() without options. This shows the full object excluding non-enumerable symbols and properties.
%% - A single percent sign ('%'). This does not consume an argument.

If a placeholder does not have a corresponding argument, it is not replaced.

$util.format("%s:%s", "foo");
// Returns: 'foo:%s'

If more arguments are passed than there are placeholders, the extra arguments are coerced to strings and appended to the result, separated by spaces. Extra arguments whose typeof is 'object' or 'symbol' (except null) are converted using $util.inspect().

$util.format("%s:%s", "foo", "bar", "baz"); // 'foo:bar baz'

If the first argument is not a string, $util.format() returns a string that is the space-separated concatenation of all arguments. Each argument is converted using $util.inspect().

$util.format(1, 2, 3); // '1 2 3'

If only one argument is passed to $util.format(), it is returned as-is without formatting.

$util.format("%% %s"); // '%% %s'

$util.log(string[, ...args])

string {string} Log format string
...args {any} Optional arguments

Outputs a log line prefixed with a timestamp. The format is usually:

DD MMM HH:mm:ss - message

This behaves like $util.format(): it formats first, then writes to the log.

$util.log("test");
// Example output: 26 Feb 21:01:14 - test

$util.log("value=%d, name=%s", 123, "demo");

$util.inspect(object[, options])

object {any} Any JavaScript primitive or object.
options {Object}
- showHidden {boolean} If true, non-enumerable symbols and properties of object are included. Default false.
- depth {number} Recursion depth when formatting object. Useful for large complex objects. Default 2. Pass null for unlimited recursion.
colors {boolean} If true, output will use ANSI color codes. Default false. Colors are customizable; see Customizing $util.inspect colors.
customInspect {boolean} If false, custom inspect(depth, opts) functions on the inspected object are not called. Default true.

$util.inspect() returns a string representation of object, primarily for debugging. You can pass extra options to change formatting behavior.

The following example inspects all properties on $util:

console.log($util.inspect($util, \{ showHidden: true, depth: null \}));

Values can provide their own custom inspect(depth, opts) functions. When called, they receive the current depth and the options object passed to $util.inspect() during recursive inspection.

$util.extend(target, source)

target {object} Target constructor
source {object} Source constructor to inherit from

Inherit prototype methods from one constructor to another, similar to Node.js util.inherits.

function SuperClass() {
  this.value = 1;
}

SuperClass.prototype.increment = function () {
  this.value++;
};

$util.extend(ChildClass, SuperClass);

function ChildClass() {
  SuperClass.call(this);
}

ChildClass.prototype.print = function () {
  console.log(this.value);
};

let child = new ChildClass();
child.increment();
child.print();

$util.isArray(object)

object {any}

An internal alias of Array.isArray.

Returns true if the given object is an Array; otherwise false.

$util.isArray([]);
// Returns: true
$util.isArray(new Array());
// Returns: true
$util.isArray(\{\});
// Returns: false

$util.isBoolean(object)

object {any}

Returns true if the given object is a Boolean; otherwise false.

$util.isBoolean(1);
// Returns: false
$util.isBoolean(0);
// Returns: false
$util.isBoolean(false);
// Returns: true

$util.isDate(object)

object {any}

Returns true if the given object is a Date; otherwise false.

$util.isDate(new Date());
// Returns: true
$util.isDate(Date());
// false (without 'new' returns a String)
$util.isDate(\{\});
// Returns: false

$util.isError(object)

object {any}

Returns true if the given object is an Error; otherwise false.

$util.isError(new Error());
// Returns: true
$util.isError(new TypeError());
// Returns: true
$util.isError(\{ name: 'Error', message: 'an error occurred' \});
// Returns: false

Note: this method depends on Object.prototype.toString(). If the object manipulates @@toStringTag, the result may be incorrect.

let obj = \{ name: 'Error', message: 'an error occurred' \};

$util.isError(obj);
// Returns: false
obj[Symbol.toStringTag] = 'Error';
$util.isError(obj);
// Returns: true

$util.isFunction(object)

object {any}

Returns true if the given object is a Function; otherwise false.

function Foo() \{\}
let Bar = () => \{\};

$util.isFunction(\{\});
// Returns: false
$util.isFunction(Foo);
// Returns: true
$util.isFunction(Bar);
// Returns: true

$util.isNull(object)

object {any}

Returns true if the given object is strictly null; otherwise false.

$util.isNull(0);
// Returns: false
$util.isNull(undefined);
// Returns: false
$util.isNull(null);
// Returns: true

$util.isNullOrUndefined(object)

object {any}

Returns true if the given object is null or undefined; otherwise false.

$util.isNullOrUndefined(0);
// Returns: false
$util.isNullOrUndefined(undefined);
// Returns: true
$util.isNullOrUndefined(null);
// Returns: true

$util.isNumber(object)

object {any}

Returns true if the given object is a Number; otherwise false.

$util.isNumber(false);
// Returns: false
$util.isNumber(Infinity);
// Returns: true
$util.isNumber(0);
// Returns: true
$util.isNumber(NaN);
// Returns: true

$util.isObject(object)

object {any}

Returns true if the given object is strictly an Object and not a Function; otherwise false.

$util.isObject(5);
// Returns: false
$util.isObject(null);
// Returns: false
$util.isObject(\{\});
// Returns: true
$util.isObject(function() \{\});
// Returns: false

$util.isPrimitive(object)

object {any}

Returns true if the given object is a primitive; otherwise false.

$util.isPrimitive(5);
// Returns: true
$util.isPrimitive('foo');
// Returns: true
$util.isPrimitive(false);
// Returns: true
$util.isPrimitive(null);
// Returns: true
$util.isPrimitive(undefined);
// Returns: true
$util.isPrimitive(\{\});
// Returns: false
$util.isPrimitive(function() \{\});
// Returns: false
$util.isPrimitive(/^$/);
// Returns: false
$util.isPrimitive(new Date());
// Returns: false

$util.isRegExp(object)

object {any}

Returns true if the given object is a RegExp; otherwise false.

$util.isRegExp(/some regexp/);
// Returns: true
$util.isRegExp(new RegExp('another regexp'));
// Returns: true
$util.isRegExp(\{\});
// Returns: false

$util.isString(object)

object {any}

Returns true if the given object is a string; otherwise false.

$util.isString("");
// Returns: true
$util.isString("foo");
// Returns: true
$util.isString(String("foo"));
// Returns: true
$util.isString(5);
// Returns: false

$util.isUndefined(object)

object {any}

Returns true if the given object is undefined; otherwise false.

let foo = undefined;
$util.isUndefined(5);
// Returns: false
$util.isUndefined(foo);
// Returns: true
$util.isUndefined(null);
// Returns: false