Namespace: Utilities

Utilities

A generic utility object that contains functions used throughout MetacatUI to perform useful functions, but not used to store or manipulate any state about the application.
Since:
  • 2.14.0
Source:

Methods

awaitMetacatUI(optionsopt) → {Promise.<object>}

Wait for the global MetacatUI object to be available, and optionally for a specific property on it to be defined. Useful when needing to access the app user model or other properties that may not be available immediately when a module is loaded.
Parameters:
Name Type Attributes Description
options object <optional>
 Options object.
Properties
Name Type Attributes Description
maxAttempts number <optional>
 Maximum number of attempts.
delay number <optional>
 Delay between attempts in ms.
property string <optional>
 Optional property name to wait for on the MetacatUI object. If provided, the Promise won't resolve until that property is available and not undefined. Otherwise, just waits for the global MetacatUI object itself.
Since:
  • 2.37.0
Source:
Throws:
If the user model is not available in time.
Type
Error
Returns:
Promise resolving to the app user model.
Type
Promise.<object>

buildInstanceKey(options, keys, normalizersopt, separatoropt, encodeopt) → {string}

Build a unique string to represent an instance of a class, or generally, to uniquely identify a set of options or properties. The key is built from an object (e.g. config options for a class instance) by concatenating the values of specified fields. Only includes fields that have non-null/undefined values.
Parameters:
Name Type Attributes Description
options object The object containing the keys and values to build the key from.
keys Array.<string> The names of fields required to build the instance key. If a value for the key is available, it will be included. Otherwise it will be skipped.
normalizers object <optional>
 Optional object mapping field names to normalizer functions that take the raw value and return a normalized value to use for the key, for example, to normalize URLs or make strings case-insensitive.
separator string <optional>
 Separator to use between key parts. Default is "|".
encode boolean <optional>
 If true, the resulting key will be run through md5 to shorten it and ensure it's a valid string for use as a key. Default is true.
Since:
  • 2.37.0
Source:
Throws:
If keys is not a non-empty array, or if buildInstanceKey is not a function.
Type
Error
Returns:
The generated instance key, which is a concatenation of the specified fields and their values, with non-string values converted to strings. If encode is true, this will be an md5 hash of the concatenated string.
Type
string

bytesToSize(bytes, precisionopt) → {string}

Convert number of bytes into human readable format
Parameters:
Name Type Attributes Description
bytes number The number of bytes
precision number <optional>
 The number of decimal places to include
Source:
Returns:
The formatted size string
Type
string

deepEqual(a, b) → {boolean}

Checks if two objects are deeply equal. Simpler than the _.isEqual function.
Parameters:
Name Type Description
a object The first object to compare
b object The second object to compare
Since:
  • 2.31.0
Source:
Returns:
True if the objects are deeply equal
Type
boolean

encodeHTML(s) → {string}

HTML-encodes the given string so it can be inserted into an HTML page without running any embedded Javascript.
Parameters:
Name Type Description
s string String to be encoded.
Source:
Returns:
HTML encoded string.
Type
string

formatFixedNumber(value, digitsopt, fallbackopt) → {string}

Format a finite number using a fixed number of decimal places.
Parameters:
Name Type Attributes Default Description
value number The number value to be formatted.
digits number <optional>
 2 The number of decimal places to display.
fallback string <optional>
 "" The value to return when `value` is not finite.
Since:
  • 2.37.0
Source:
Returns:
A fixed-decimal number string or the fallback value.
Type
string

formatNumber(value, range) → {string}

Format the number into a string with better readability, based on the manitude of a range this number falls in.
Parameters:
Name Type Description
value number The number value to be formatted.
range number The range of numerics this value can fall in.
Since:
  • 2.30.0
Source:
Returns:
A formatted number based on the magnitude of `range`.
Type
string

getCaseInsensitive(obj, keyName, normalizeValueopt) → {*}

Get a value from a plain object using a case-insensitive key.
Parameters:
Name Type Attributes Description
obj object Source object
keyName string Key name to look up (case-insensitive)
normalizeValue function <optional>
 Optional value normalizer
Since:
  • 2.37.0
Source:
Returns:
The matched value, or undefined if not found
Type
*

getNumDecimalPlaces(range) → {number}

Calculate the number of decimal places we should use based on the range of the data.
Parameters:
Name Type Description
range number The range of data values.
Since:
  • 2.30.0
Source:
Returns:
The number of decimal places we should use.
Type
number

getSingleton(ClassRef, optionsopt, buildInstanceKey) → {object}

Get or create a singleton instance for a class.
Parameters:
Name Type Attributes Description
ClassRef function Class reference.
options object <optional>
 Options passed to the class constructor for this instance.
buildInstanceKey function Function that builds a unique key for the instance based on the options. This is used to allow multiple singletons for the same class with different options. The function will be passed the options object and should return a string key.
Since:
  • 2.37.0
Source:
Returns:
The singleton instance.
Type
object

isValidDOI(identifier) → {boolean}

Validates that the given string is a valid DOI
Parameters:
Name Type Description
identifier string String to be validated.
Since:
  • 2.15.0
Source:
Returns:
True if identifier is a valid DOI.
Type
boolean

normalizeUrl(url, fallbackopt) → {string}

Normalize a URL string by trimming whitespace and removing trailing slashes.
Parameters:
Name Type Attributes Description
url string The URL to normalize.
fallback string <optional>
 A fallback URL to use if url is empty.
Since:
  • 2.37.0
Source:
Returns:
Normalized URL, or empty string if not available.
Type
string

readSlice(file, context, callback, bytes)

Read the first part of a file
Parameters:
Name Type Description
file File A reference to a file
context Backbone.View The View to bind `callback` to
callback function A function to run after the read is complete. The function is bound to `context`.
bytes number The number of bytes to read from the start of the file
Since:
  • 2.15.0
Source:

stableStringify(val, optionsopt) → {string}

Stringify any value deterministically, where order doesn't impact the result. All object keys and array items are sorted in a consistent way. Normalizes undefined to null. Useful for creating unique keys based on the content of an object, e.g. for keying a cache or singleton instance.
Parameters:
Name Type Attributes Description
val * The value to stringify.
options object <optional>
 Options object.
Properties
Name Type Attributes Description
ignoreCase boolean <optional>
 Whether to convert all string values to lower case before stringifying, for case-insensitive comparisons. Default is true. Note when ignoreCase is true, normalized object keys can collide (e.g., "A" and "a").
processed WeakSet <optional>
 WeakSet tracking visited objects.
orderMatters boolean <optional>
 Whether to preserve array order during stringification. Default is false (arrays are sorted).
Since:
  • 2.37.0
Source:
Throws:
If a circular reference is detected.
Type
Error
Returns:
A string that is consistent regardless of the order of keys in objects or items in arrays, etc.
Type
string

toJSONWithoutDefaults(model, removePropsopt) → {object}

Removes default values from a model's JSON representation
Parameters:
Name Type Attributes Description
model Backbone.Model The model to remove defaults from
removeProps Array.<string> <optional>
 An array of additional properties to remove from the model
Since:
  • 2.31.0
Source:
Returns:
The JSON representation of the model with defaults removed
Type
object

tryParseCSVHeader(text) → {Array}

Attempt to parse the header/column names from a chunk of a CSV file Doesn't handle: - UTF BOM (garbles first col name) - Commas inside quoted headers
Parameters:
Name Type Description
text string A chunk of a file
Since:
  • 2.15.0
Source:
Returns:
A list of names
Type
Array

wildcardToRegex(pattern) → {RegExp}

Convert a wildcard pattern (e.g. "eml*", "*iso*") to a safe RegExp. Escapes all regex special chars except '*' which becomes '.*'
Parameters:
Name Type Description
pattern string A simple wildcard pattern
Source:
Returns:
Regex for case-insensitive matching
Type
RegExp