A collection of commonly needed utilities used by the Salesforce CLI and the libraries it is built on. It includes high level support for parsing and working with JSON data, interacting with environment variables, a common error base type, a minimal lodash replacement, and support for commonly needed design patterns, among other things. It is intended specifically for use in Node.js (version 8 or newer) projects -- YMMV in the browser.
See the API documentation for more details on each of the utilities that kit provides.
This library depends upon another Salesforce TypeScript library, @salesforce/ts-types. The API documentation for this library refers to several types that you will find in ts-types. Some lodash replacement functions are also found in ts-types.
The default Env instance, which wraps process.env.
Perform a deep clone of an object or array compatible with JSON stringification.
Object fields that are not compatible with stringification will be omitted. Array
entries that are not compatible with stringification will be censored as null.
A JSON-compatible object or array to clone.
Assigns own enumerable properties of source object(s) to the destination object for all destination properties that resolve to undefined. Once a property is set, additional values of the same property are ignored.
Note: This method mutates obj.
The destination object.
This method is like find except that it returns the key of the first element predicate returns truthy for
instead of the element itself.
The object to search.
The function invoked per iteration.
Finds all elements of type T with a given name in a JsonMap. Not suitable for use
with object graphs containing circular references. The specification of an appropriate
type T that will satisfy all matching element values is the responsibility of the caller.
The JsonMap tree to search for elements of the given name.
The name of elements to search for.
Checks if target is in collection using SameValueZero for equality comparisons. If fromIndex is negative, it’s used as the offset from the end of collection.
The collection to search.
The value to search for.
The index to search from.
Checks if value is empty. A value is considered empty unless it’s an arguments object, array, string, or jQuery-like collection with a length greater than 0 or an object with own enumerable properties.
The value to inspect.
Tests whether an AnyJson value contains another AnyJson value. This is a shallow
check only and does not recurse deeply into collections.
The container to search.
The value search for.
Creates an object composed of keys generated from the results of running each element of collection through iteratee. The corresponding value of each key is the last element responsible for generating the key. The iteratee function is invoked with one argument: (value).
The collection to iterate over.
The function invoked per iteration.
Converts the first character of string to lower case.
This method creates an object with the same values as object and keys generated by running each own enumerable property of object through iteratee.
The function invoked per iteration.
This method is like _.max except that it accepts iteratee which is
invoked for each element in array to generate the criterion by which
the value is ranked. The iteratee is invoked with one argument: (value).
The iteratee invoked per element.
Recursively merges own and inherited enumerable properties of source
objects into the destination object, skipping source properties that resolve
to undefined. Array and plain object properties are merged recursively.
Other objects and value types are overridden by assignment. Source objects
are applied from left to right. Subsequent sources overwrite property
assignments of previous sources.
Note: This method mutates object.
The destination object.
This method is like _.min except that it accepts iteratee which is
invoked for each element in array to generate the criterion by which
the value is ranked. The iteratee is invoked with one argument: (value).
The iteratee invoked per element.
The opposite of _.pick; this method creates an object composed of the
own and inherited enumerable properties of object that are not omitted.
The source object.
The property names to omit, specified individually or in arrays..
Creates a function that is restricted to invoking func once. Repeat calls to the function return the value
of the first call. The func is invoked with the this binding and arguments of the created function.
The function to restrict.
Parse JSON string data.
Data to parse.
The file path from which the JSON was loaded.
If the data contents are empty.
Parse JSON string data, expecting the result to be a JsonMap.
The string data to parse.
The file path from which the JSON was loaded.
If the data contents are empty.
Sets the value at path of object. If a portion of path doesn’t exist it’s created. Arrays are created for missing index properties while objects are created for all other missing properties. Use _.setWith to customize path creation.
The object to modify.
The path of the property to set.
The value to set.
Sleeps for a given Duration. This is essentially a promisified version of setTimeout. May be interrupted
by calling interrupt() on the returned InterruptablePromise.
The duration to wait.
// sleep 5 seconds
await sleep(Duration.seconds(5));
// sleep 10 minutes unless interrupted by an event
const promise = sleep(Duration.minutes(10));
events.on('someEvent', promise.interrupt);
await promise;Sleeps for a given duration, with units defaulting to milliseconds. This is essentially a promisified version
of setTimeout. May be interrupted by calling interrupt() on the returned InterruptablePromise.
The quantity of duration to wait.
The Duration.Unit in which quantity is specified, defaulting to milliseconds.
// sleep 5 seconds
await sleep(5000);
// sleep 10 minutes unless interrupted by an event
const promise = sleep(10, Duration.Unit.MINUTES);
events.on('someEvent', promise.interrupt);
await promise;Converts string to snake case.
The string to convert.
Creates an array of elements, sorted in ascending order by the results of running each element in a collection through each iteratee. This method performs a stable sort, that is, it preserves the original sort order of equal elements. The iteratees are invoked with one argument: (value).
The collection to iterate over.
The iteratees to sort by, specified individually or in arrays.
Converts value to a number.
The value to process.
_.toNumber(3);
// => 3
_.toNumber(Number.MIN_VALUE);
// => 5e-324
_.toNumber(Infinity);
// => Infinity
_.toNumber('3');
// => 3Converts the first character of string to upper case.
A promise of result type
Tthat can be interrupted prematurely, resulting in an early resolution.