Util - Documentation

Constructor

new Util()

Source:

core/util.js, line 15

Methods

(static) arrayContentsMatch(a, b, orderMatters) → {boolean}

Returns true if arrays a and b contain the same elements, regardless of order. When specifying orderMatters = false, be careful using this with large arrays, since it copies and sorts each array. This is intended for arrays of scalar values like strings, numbers, and dates, whose values can be compared for simple equality.

Parameters:

Name	Type	Description
`a`	Array	The first array.
`b`	Array	The second array.
`orderMatters`	boolean	Set this to true if the arrays must contain the same elements in the same order. Set to false to check if they contain the same elements in any order.

Source:

core/util.js, line 558

(static) bagNameFromPath(filepath)

This function returns the basename of the given file path with with the following extensions stripped off:

.7z, .s7z
.bz, .bz2
.gz
.par, par2
.rar
.tar, .tar.gz, .tgz, .tar.Z
.zip, .zipx

The point is to return the expected name of the bag, based on the file path. If the file's basename has an unrecognized extension or no extension, this will return the basename unaltered.

Parameters:

Name	Type	Description
`filepath`	string	Path to the bag.

Source:

core/util.js, line 457

(static) boolEqual(a, b) → {boolean}

Returns true if a and b are both non-null and both indicate the same truth value. E.g. true = "true" = "yes" and false = "false" = "no".

Parameters:

Name	Type	Description
`a`	boolean \| string	First value to compare.
`b`	boolean \| string	Second value to compare.

Source:

core/util.js, line 207

(static) boolValue(val) → {boolean}

Returns the boolean value of a string. "true" and "yes" are true. "false" and "no" are false. String is case-insensitive.

Parameters:

Name	Type	Description
`val`	boolean \| string	The value to examine.

Source:

core/util.js, line 222

(static) camelToTitle(str) → {string}

Converts a camel case variable name to title-cased text. For example, myVarName is converted to My Var Name. This is useful for converting var names to labels in the UI.

Parameters:

Name	Type	Description
`str`	string	The string to convert

Source:

core/util.js, line 115

(static) canRead(filepath) → {boolean}

Returns true if the file at filepath is readable by the current user/application.

Parameters:

Name	Type	Description
`filepath`	string	The path the the file.

Source:

core/util.js, line 585

(static) canWrite() → {boolean}

Returns true if the file at filepath is writable by the current user/application.

Source:

core/util.js, line 602

(static) cast(str, toType)

This casts the string value str to type toType and returns the cast value. This is used primarily for converting values from HTML forms to correctly-typed JavaScript values.

Parameters:

Name	Type	Description
`str`	string	The string value to be cast.
`toType`	string	The type to which the string value should be cast. Currently supports only 'number' and 'boolean'.

Source:

core/util.js, line 479

Example

Util.cast('false', 'boolean') // returns false
Util.cast('yes', 'boolean')   // returns true
Util.cast('1', 'boolean')     // returns true
Util.cast('3', 'number')      // returns 3
Util.cast('3.14', 'number')   // returns 3.14

(static) deleteFromArray(array, item)

This deletes up to one item from an array, modifying the array in place. For example, Util.deleteFromArray(list, "butter") will delete the first instance of the word "butter" from the array, or will delete nothing if the array does not contain that word.

Parameters:

Name	Type	Description
`array`	Array	A list of items.
`item`	string \| number \| boolean \| Date	The item you want to delete.

Source:

core/util.js, line 432

(static) deleteRecursive(dir)

Recursively and synchronously deletes a directory and all its contents. This will throw an exception if you try to delete any path that's too close to the root of the file system (fewer than 8 characters or fewer than 3 slashes/backslashes).

Parameters:

Name	Type	Description
`dir`	string	Path to the directory you want to delete.

Source:

core/util.js, line 379

(static) escapeBackslashes(winPath) → {string}

Replaces backslashes in Windows paths with double backslashes.

Parameters:

Name	Type	Description
`winPath`	string	A Windows path.

Source:

core/util.js, line 297

(static) filterEmptyStrings(arr) → {Array.<string>}

Returns an array of strings, with all null and empty strings removed.

Parameters:

Name	Type	Description
`arr`	Array.<string>	The list of strings to filter.

Source:

core/util.js, line 146

(static) findCommonPathPrefix(paths, pathSep) → {string}

Given a list of file paths, this returns the prefix common to all paths. This function probably has worse than 0n^2 efficiency, so it's OK if paths.length < 10, but it probably gets pretty bad from there.

If paths have nothing in common, this returns an empty string.

Parameters:

Name	Type	Description
`paths`	Array.<string>	List of paths to compare.
`pathSep`	string	Optional param to specify the path separator. This defaults to the operating system's path.sep, so you don't need to specify this.

Source:

core/util.js, line 671

Example

let posixPaths = [
    "/path/to/some/file.txt",
    "/path/to/some/other/document.pdf",
    "/path/to/some/different/photo.jpg"
]

Util.findCommonPathPrefix(posixPaths); // returns "/path/to/some/"

let windowPaths = [
    "c:\\path\\to\\some\\file.txt",
    "c:\\path\\to\\some\\other\\file.txt",
    "c:\\path\\to\\some\\different\\file.txt",
]

Util.findCommonPathPrefix(windowsPaths); // returns "c:\\path\\to\\some\\"

(static) forkJobProcess(job) → {Object}

Launches a Job in a separate process. Returns an object with keys childProcess and dartProcess.

Parameters:

Name	Type	Description
`job`	Job	The job to run in the child process.

Source:

core/util.js, line 732

(static) formatError(err) → {string}

Returns a human-readable version of an error. This works for native JavaScript Error object and Node.js's syscall errors. If err is a string, it returns err unchanged. If it's none of those types, this returns a JSON string of the error.

Parameters:

Name	Type	Description
`err`	Object	An Error, Node SystemError, or other object.

Source:

core/util.js, line 765

(static) getEnvSetting(str) → {string}

This returns the value of an environment variable, if the variable is available. Certain variables, such as the login credentials used in the StorageService class may be stored more safely as environment variables outside of the DART database. Those variables follow the pattern env:VAR_NAME.

If you pass env:VAR_NAME to this function, it will return the value of the environment variable VAR_NAME.

Parameters:

Name	Type	Description
`str`	string	A string in the format env:VAR_NAME.

Source:

core/util.js, line 519

(static) getSortFunction(property, direction) → {function}

Returns a function suitable for sorting a list of objects in ascending or desdending order.

Parameters:

Name	Type	Description
`property`	string	The name of the object property to sort on.
`direction`	string	'desc' or 'asc' for descending or ascending.

Source:

core/util.js, line 180

(static) isDirectory() → {boolean}

Returns true if dirpath is a directory.

Source:

core/util.js, line 619

(static) isEmpty(str) → {boolean}

Returns true if str is null or empty.

Parameters:

Name	Type	Description
`str`	string	The string to check.

Source:

core/util.js, line 103

(static) isEmptyStringArray(arr) → {boolean}

Returns true if array of strings is empty, or if all elements of the array are null or empty.

Parameters:

Name	Type	Description
`arr`	Array.<string>	The list of strings to check.

Source:

core/util.js, line 127

(static) isNonEmptyDirectory() → {boolean}

Returns true if dirpath is a non-empty directory.

Source:

core/util.js, line 630

(static) lcFirst(str) → {string}

Returns a copy of string str with the first letter set to lowercase. Returns null if param str is null.

Parameters:

Name	Type	Description
`str`	string

Source:

core/util.js, line 283

(static) listContains(list, item) → {boolean}

Returns true if list contains item. The list should contain simple scalar values that can be compared with a simple equality test. This is similar to the builtin array.includes(), but includes some special handling for boolean values.

Parameters:

Name	Type	Description
`list`	Array.<string> \| Array.<number> \| Array.<boolean>	The list items to search.
`item`	string \| number \| boolean	The item to look for.

Source:

core/util.js, line 163

(static) looksLikeEnvSetting(settingValue) → {boolean}

This returns true if settingValue begins with "env:".

Parameters:

Name	Type	Description
`settingValue`	string	The value of the setting.

Source:

core/util.js, line 500

(static) looksLikeHypertextURL(str) → {boolean}

Returns true if str matches the regex for a URL beginning with http or https and looks like a valid URL.

Parameters:

Name	Type	Description
`str`	string	The string to test.

Source:

core/util.js, line 82

(static) looksLikeUUID(str) → {boolean}

Returns true if str matches the regex for hex-formatted uuid.

Parameters:

Name	Type	Description
`str`	string	The string to test.

Source:

core/util.js, line 70

(static) normalizeWindowsPath(winPath) → {string}

Converts an absolute Windows path to a path with forward slashes suitable for a BagIt file or tar file. Also strips off drive letters and share names.

Parameters:

Name	Type	Description
`winPath`	string	An absolute Windows path.

Source:

core/util.js, line 310

(static) removeWindowsDrivePrefix(winPath) → {string}

Strips off drive letters and share names from Windows paths. E.g. "C:\some\path" becomes "\some\path" and "\share\some\path" becomes "\some\path"

Parameters:

Name	Type	Description
`winPath`	string	An absolute Windows path.

Source:

core/util.js, line 325

(static) tmpFilePath() → {string}

Returns a path to a temp file, without actually creating the file.

Source:

core/util.js, line 531

(static) toHumanSize(bytes) → {string}

toHumanSize returns a human-readable size for the given number of bytes. The return value is trucated at two decimal places. E.g. 2621440 converts to "2.50 MB"

Parameters:

Name	Type	Description
`bytes`	number	The number of bytes to convert to human size.

Source:

core/util.js, line 246

(static) trimToLength(str, len, trimFrom) → {string}

Returns str trimmed to the specified length, with trimmed characters replaced by '...'. If str is already less than or equal to len characters, this returns the string unchanged. If len is too short, the return value will likely be '...'.

Parameters:

Name	Type	Description
`str`	string	The string to trim.
`len`	number	The length to trim to.
`trimFrom`	string	Where to trim the excess characters from. Valid values are 'end' and 'middle'. Any other value is interpreted as 'middle'.

Source:

core/util.js, line 707

(static) truncateString(str, len) → {string}

Truncates a string at len characters, and appends '..." to the end.

Parameters:

Name	Type	Description
`str`	string	The string to truncate.
`len`	number	Truncate the string at len characters.

Source:

core/util.js, line 268

(static) unicodeByteLength(str) → {number}

Returns the byte length of an utf8 string

Parameters:

Name	Type	Description
`str`	string	The string to measure.

Source:

core/util.js, line 53

(static) uuid4() → {string}

Returns a version 4 uuid string.

Thanks https://gist.github.com/kaizhu256/4482069

Source:

core/util.js, line 23

(static) walkSync(dir, filterFunction) → {Array.<string>}

walkSync recursively lists all files in a directory and its subdirectories and returns them in filelist. If you want to filter the list, include a callback filterFunction, which takes the filepath as its sole param (a string) and returns true or false to indicate whether to include the file in the list.

The returned list is a list of hashes, and each hash has keys absPath: the absolute path to the file stats: a Node fs.Stats object with info about the file The returned list will not include links, only files.

Parameters:

Name	Type	Description
`dir`	string	Path to directory.
`filterFunction`	filterFunction	A function to filter out items that should not go into filelist.

Source:

core/util.js, line 348