@zowe/imperative
Version:
framework for building configurable CLIs
272 lines • 11.7 kB
JavaScript
;
/*
* This program and the accompanying materials are made available under the terms of the
* Eclipse Public License v2.0 which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-v20.html
*
* SPDX-License-Identifier: EPL-2.0
*
* Copyright Contributors to the Zowe Project.
*
*/
Object.defineProperty(exports, "__esModule", { value: true });
exports.ImperativeExpect = void 0;
const error_1 = require("../../error");
const util_1 = require("util");
const DataObjectParser = require("dataobject-parser");
/**
* Helper class for paramter validation. Expectations that fail will throw an ImperativeError with a validation
* error message.
*
* All methods allow keys to be specified as "property1.prop.lastprop" for example.
*
* @export
* @class ImperativeExpect
*/
class ImperativeExpect {
/**
* Expect a situation and transform the error (if expect fails).
* Accepts two methods of your implementation to:
* A) Test the expect (which is intended to throw an ImperativeError)
* B) Transform and return a new ImperativeError
* This allows you complete control over the contents of the error. If you are only interested in influencing the
* message displayed, then use the msg parm on each of the expect functions.
* @static
* @param {() => void} expect - The method that contains your ImperativeExpect invocation
* @param {(error: any) => ImperativeError} transform - Passed the error thrown by the expect and expects you
* to return the ImperativeError you would like thrown.
* @memberof ImperativeExpect
*/
static expectAndTransform(expect, transform) {
try {
expect();
}
catch (error) {
if (error instanceof error_1.ImperativeError) {
throw transform(error);
}
else {
throw new error_1.ImperativeError({
msg: "Expect and Transform is expecting that the expect method throws an ImperativeError."
}, {
tag: ImperativeExpect.ERROR_TAG
});
}
}
}
/**
* Expect that values are equal (via "!==" operator).
* @static
* @param {*} value1 - Value 1
* @param {*} value2 - Value 2
* @param {string} [msg] - The message to throw - overrides the default message
* @memberof ImperativeExpect
*/
static toBeEqual(value1, value2, msg) {
if (value1 !== value2) {
throw new error_1.ImperativeError({ msg: msg || "Input objects/values are NOT equal" }, { tag: ImperativeExpect.ERROR_TAG });
}
}
/**
* Expect that value matches the regular expression (via ".test()" method).
* @static
* @param {*} value - Value
* @param {*} myRegex - Regular expression
* @param {string} [msg] - The message to throw - overrides the default message
* @memberof ImperativeExpect
*/
static toMatchRegExp(value, myRegex, msg) {
if (!new RegExp(myRegex).test(value)) {
throw new error_1.ImperativeError({ msg: msg || "Input object/value does not match the regular expression" }, { tag: ImperativeExpect.ERROR_TAG });
}
}
/**
* Expect the object passed to be defined.
* @static
* @param {*} obj - The object to check
* @param {string} [msg] - The message to throw - overrides the default message
* @memberof ImperativeExpect
*/
static toNotBeNullOrUndefined(obj, msg) {
if (obj == null) {
throw new error_1.ImperativeError({ msg: msg || "Required object must be defined" }, { tag: ImperativeExpect.ERROR_TAG });
}
}
/**
* Expect the object passed to be an array that contains a particular entry.
* Your compare method is invoked to determine if the entry you're looking for is found within the array.
* @static
* @param {any[]} arr - the array to search
* @param {(parms: any) => boolean} compare - compare method (passed the parms) - return true if the entry is
* found within the array.
* @param {string} [msg] - The message to throw - overrides the default message
* @returns {*} - If a match is found, it will return the match.
* @memberof ImperativeExpect
*/
static arrayToContain(arr, compare, msg) {
ImperativeExpect.toBeAnArray(arr, msg);
let foundEntry;
for (const entry of arr) {
if (compare(entry)) {
foundEntry = entry;
break;
}
}
if (foundEntry == null) {
throw new error_1.ImperativeError({
msg: msg || "The required entry was NOT found within the input array: " +
arr.map((entry) => (0, util_1.inspect)(entry))
}, { tag: ImperativeExpect.ERROR_TAG });
}
return foundEntry;
}
/**
* Check if the input is one of several possibilities in a list.
* @static
* @param {*} value - The value to find in following array
* @param {any[]} arr - The array of possible items we could be expecting
* @param {string} [msg] - The message - overrides the default message
* @returns {*} - If a match is found, it will return the match.
* @memberof ImperativeExpect
*/
static toBeOneOf(value, arr, msg) {
ImperativeExpect.toNotBeNullOrUndefined(value, msg);
return ImperativeExpect.arrayToContain(arr, (entry) => {
return entry === value;
}, msg);
}
/**
* Check if the input object is an array.
* @static
* @param {any[]} arr - The array to check
* @param {string} [msg] - The message to throw - overrides the default message
* @memberof ImperativeExpect
*/
static toBeAnArray(arr, msg) {
ImperativeExpect.toNotBeNullOrUndefined(arr, msg);
if (!Array.isArray(arr)) {
throw new error_1.ImperativeError({ msg: msg || "Required parameter '" + arr + "' must be an array." }, { tag: ImperativeExpect.ERROR_TAG });
}
}
/**
* Expect a set of keys (by name) to be defined, of type array, and optionally a non-zero length array.
* @static
* @param obj - the object for which you would like to assert that certain fields
* @param nonZeroLength if true, the length of the array must be non zero
* @param {...string[]} keys - keys in object that should be arrays
* @param {string} [msg] - The message to throw - overrides the default message
*/
static keysToBeAnArray(obj, nonZeroLength, keys, msg) {
ImperativeExpect.toNotBeNullOrUndefined(obj, msg);
const objParser = new DataObjectParser(obj);
keys.forEach((key) => {
if (objParser.get(key) == null) {
throw new error_1.ImperativeError({ msg: msg || "Required parameter '" + key + "' must be defined" }, { tag: ImperativeExpect.ERROR_TAG });
}
ImperativeExpect.toBeAnArray(objParser.get(key), msg);
const arr = objParser.get(key);
if (nonZeroLength) {
if (arr.length === 0) {
throw new error_1.ImperativeError({ msg: msg || "Required parameter '" + key + "' must be an array with at least 1 entry." }, { tag: ImperativeExpect.ERROR_TAG });
}
}
});
}
/**
* Expect a set of keys (by name) are defined.
* @static
* @param {{[key: string]: any}} obj - object to test existence
* @param {...string[]} keys - keys in object
* @param {string} [msg] - The message to throw - overrides the default message
* @memberof ImperativeExpect
*/
static keysToBeDefined(obj, keys, msg) {
ImperativeExpect.toNotBeNullOrUndefined(obj, msg);
const objParser = new DataObjectParser(obj);
keys.forEach((key) => {
if (objParser.get(key) == null) {
throw new error_1.ImperativeError({ msg: msg || "Required parameter '" + key + "' must be defined" }, { tag: ImperativeExpect.ERROR_TAG });
}
});
}
/**
* Expect two values to be equal (via "===" operator).
* @static
* @param {*} value1 - Value 1
* @param {*} value2 - Value 2
* @param {string} [msg] - The message to throw - overrides the default message
* @memberof ImperativeExpect
*/
static toNotBeEqual(value1, value2, msg) {
if (value1 === value2) {
throw new error_1.ImperativeError({ msg: msg || 'Values specified are equal ("' + value1 + '")' }, { tag: ImperativeExpect.ERROR_TAG });
}
}
/**
* Expect that a set of keys are defined, of type string, and are non-blank (after trimming).
* @static
* @param {{[key: string]: string}} obj - object to test existence
* @param {...string[]} keys - keys in object
* @param {string} [msg] - The message to throw - overrides the default message
* @memberof ImperativeExpect
*/
static keysToBeDefinedAndNonBlank(obj, keys, msg) {
ImperativeExpect.keysToBeDefined(obj, keys, msg);
ImperativeExpect.keysToBeOfType(obj, "string", keys, msg);
const objParser = new DataObjectParser(obj);
keys.forEach((key) => {
if (objParser.get(key).trim().length === 0) {
throw new error_1.ImperativeError({ msg: msg || "Required parameter '" + key + "' must not be blank" }, { tag: ImperativeExpect.ERROR_TAG });
}
});
}
static toBeDefinedAndNonBlank(item, label, msg) {
ImperativeExpect.toNotBeNullOrUndefined(item, msg);
if (item.toString().trim().length === 0) {
throw new error_1.ImperativeError({ msg: "Required parameter '" + label + "' must not be blank" }, { tag: ImperativeExpect.ERROR_TAG });
}
}
/**
* Expect a set of keys to be of a certain type.
* @static
* @param {{ [key: string]: any }} obj - The input object
* @param {string} type - The type to check for (only primatives - uses "typeof")
* @param {...string[]} keys - A list of keys to check in the object
* @param {string} [msg] - The message to throw - overrides the default message
* @memberof ImperativeExpect
*/
static keysToBeOfType(obj, type, keys, _msg) {
ImperativeExpect.keysToBeDefined(obj, keys);
const objParser = new DataObjectParser(obj);
keys.forEach((key) => {
if (typeof objParser.get(key) !== type) {
throw new error_1.ImperativeError({ msg: "Object key '" + key + "' must be of type '" + type + "'" }, { tag: ImperativeExpect.ERROR_TAG });
}
});
}
/**
* Expect a set of keys to be undefined.
* @static
* @param {{[key: string]: any}} obj - object to test existence
* @param {...string[]} keys - keys in object
* @param {string} [msg] - The message to throw - overrides the default message
* @memberof ImperativeExpect
*/
static keysToBeUndefined(obj, keys, msg) {
ImperativeExpect.toNotBeNullOrUndefined(obj, msg);
keys.forEach((key) => {
if (!(obj[key] == null)) {
throw new error_1.ImperativeError({ msg: "Required parameter '" + key + "' must be undefined" }, { tag: ImperativeExpect.ERROR_TAG });
}
});
}
}
exports.ImperativeExpect = ImperativeExpect;
/**
* The error tag to append to each error message.
* @static
* @type {string}
* @memberof ImperativeExpect
*/
ImperativeExpect.ERROR_TAG = "Expect Error";
//# sourceMappingURL=ImperativeExpect.js.map