@augment-vir/common 6.4.0 → 7.0.0

package/dist/cjs/augments/common-number.d.ts

@@ -1,4 +1,5 @@
-export declare function addCommasToNumber(input: number): string;
+export declare const NaNString: string;
+export declare function addCommasToNumber(input: number | string): string;
 export declare function clamp(
 /**
  * This uses a destructured object so that consumers cannot get confused as to which input is
@@ -9,25 +10,6 @@ export declare function clamp(
     min: number;
     max: number;
 }): number;
-/**
- * This truncates a number such that is will at a max have 6 characters including suffix, decimal
- * point, or comma.
- *
- * Default suffixes are:
- *
- *     '', // no suffix, numbers below 1000
- *     'k', // thousand
- *     'M', // million
- *     'B', // billion
- *     'T', // trillion
- *     'P', // peta-, quadrillion
- *     'E', // exa- quintillion
- *     'Z', // zetta- sextillion
- *     'Y', // yotta- septillion
- */
-export declare function truncateNumber(originalValue: unknown, { customSuffixes, suppressErrorLogging, customErrorLogCallback, }?: {
-    customSuffixes?: ReadonlyArray<string>;
-    suppressErrorLogging?: boolean;
-    customErrorLogCallback?: (...args: any) => void;
-}): string;
+export declare function convertIntoNumber(input: unknown): number;
+export declare function doesRequireScientificNotation(input: number): boolean;
 //# sourceMappingURL=common-number.d.ts.map

package/dist/cjs/augments/common-number.js

@@ -1,9 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.truncateNumber = exports.clamp = exports.addCommasToNumber = void 0;
+exports.doesRequireScientificNotation = exports.convertIntoNumber = exports.clamp = exports.addCommasToNumber = exports.NaNString = void 0;
 const common_string_1 = require("./common-string");
 const regexp_1 = require("./regexp");
+exports.NaNString = String(NaN);
 function addCommasToNumber(input) {
+    if (typeof input === 'string' && isNaN(Number(input))) {
+        return exports.NaNString;
+    }
     const stringValue = String(input);
     const [digits, decimalValues,] = stringValue.split('.');
     const decimalString = decimalValues ? `.${decimalValues}` : '';
@@ -23,89 +27,19 @@ function clamp(
     return Math.max(Math.min(value, max), min);
 }
 exports.clamp = clamp;
-const defaultTruncationSuffixes = [
-    '',
-    'k',
-    'M',
-    'B',
-    'T',
-    'P',
-    'E',
-    'Z',
-    'Y', // yotta- septillion
-];
-function recursiveTruncation(value, recursionDepth = 0, decimalValues = '') {
-    var _a;
-    if (value.includes('e+')) {
-        throw new Error(`Number is too large, it cannot be truncated: ${value}`);
+function convertIntoNumber(input) {
+    if (typeof input === 'number') {
+        return input;
     }
-    else if (value.includes('e-')) {
-        throw new Error(`Number is too small, it cannot be truncated: ${value}`);
+    else if (typeof input === 'string') {
+        return Number((0, common_string_1.removeCommasFromNumberString)(input));
     }
-    const split = (0, common_string_1.typedSplit)(value, '.');
-    decimalValues = (_a = split[1]) !== null && _a !== void 0 ? _a : decimalValues;
-    const amount = split[0];
-    if (amount.length > 3) {
-        decimalValues = amount.slice(-3);
-        return recursiveTruncation(amount.slice(0, -3), recursionDepth + 1, decimalValues);
+    else {
+        return Number(input);
     }
-    return {
-        value: amount,
-        decimalValues,
-        recursionDepth,
-    };
 }
-const maxDecimals = 4;
-/**
- * This truncates a number such that is will at a max have 6 characters including suffix, decimal
- * point, or comma.
- *
- * Default suffixes are:
- *
- *     '', // no suffix, numbers below 1000
- *     'k', // thousand
- *     'M', // million
- *     'B', // billion
- *     'T', // trillion
- *     'P', // peta-, quadrillion
- *     'E', // exa- quintillion
- *     'Z', // zetta- sextillion
- *     'Y', // yotta- septillion
- */
-function truncateNumber(originalValue, { customSuffixes, suppressErrorLogging, customErrorLogCallback, } = {}) {
-    try {
-        const value = typeof originalValue === 'number'
-            ? originalValue
-            : typeof originalValue === 'string'
-                ? Number((0, common_string_1.removeCommasFromNumberString)(originalValue))
-                : Number(originalValue);
-        if (isNaN(value)) {
-            throw new Error(`${originalValue} could not be converted into a number.`);
-        }
-        const stringValue = String(value);
-        const results = recursiveTruncation(stringValue);
-        const suffixes = customSuffixes !== null && customSuffixes !== void 0 ? customSuffixes : defaultTruncationSuffixes;
-        const suffix = suffixes[results.recursionDepth];
-        if (suffix === undefined) {
-            throw new Error(`Number is too large, could not truncate: ${value}`);
-        }
-        const decimalPlaces = maxDecimals - (results.value.length - 1) - suffix.length;
-        const decimalValues = results.decimalValues.replace(/0+$/, '').slice(0, decimalPlaces);
-        const withDecimal = decimalValues.length ? `.${decimalValues}` : '';
-        const combined = `${results.value}${withDecimal}${suffix}`;
-        if (combined.length > stringValue.length + 1) {
-            return addCommasToNumber(value);
-        }
-        else {
-            return combined;
-        }
-    }
-    catch (error) {
-        const errorCallback = customErrorLogCallback ? customErrorLogCallback : console.error;
-        if (!suppressErrorLogging) {
-            errorCallback(error);
-        }
-        return String(originalValue);
-    }
+exports.convertIntoNumber = convertIntoNumber;
+function doesRequireScientificNotation(input) {
+    return String(input).includes('e');
 }
-exports.truncateNumber = truncateNumber;
+exports.doesRequireScientificNotation = doesRequireScientificNotation;

package/dist/cjs/augments/error.d.ts

@@ -1,4 +1,6 @@
+import { NoInputsFunction } from './function';
 import { AtLeastTuple } from './tuple';
+import { UnPromise } from './type';
 export declare function combineErrors(errors: AtLeastTuple<Error, 1>): Error;
 export declare function combineErrors(errors: ReadonlyArray<never>): undefined;
 export declare function combineErrors(errors: ReadonlyArray<Error>): Error | undefined;
@@ -6,4 +8,6 @@ export declare function combineErrors(errors?: undefined): undefined;
 export declare function combineErrorMessages(errors?: ReadonlyArray<Error | string | undefined> | undefined): string;
 export declare function extractErrorMessage(error: unknown): string;
 export declare function ensureError(input: unknown): Error;
+export declare function executeAndReturnError<CallbackGeneric extends NoInputsFunction<PromiseLike<any>>>(callback: CallbackGeneric): Promise<Error | UnPromise<ReturnType<CallbackGeneric>>>;
+export declare function executeAndReturnError<CallbackGeneric extends NoInputsFunction>(callback: CallbackGeneric): Error | ReturnType<CallbackGeneric>;
 //# sourceMappingURL=error.d.ts.map

package/dist/cjs/augments/error.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ensureError = exports.extractErrorMessage = exports.combineErrorMessages = exports.combineErrors = void 0;
+exports.executeAndReturnError = exports.ensureError = exports.extractErrorMessage = exports.combineErrorMessages = exports.combineErrors = void 0;
 const function_1 = require("./function");
+const promise_1 = require("./promise");
 function combineErrors(errors) {
     if (!errors || errors.length === 0) {
         return undefined;
@@ -41,3 +42,29 @@ function ensureError(input) {
     }
 }
 exports.ensureError = ensureError;
+function executeAndReturnError(callback) {
+    let caughtError;
+    try {
+        const result = callback();
+        if ((0, promise_1.isPromiseLike)(result)) {
+            return new Promise(async (resolve) => {
+                try {
+                    const output = await result;
+                    return resolve(output);
+                }
+                catch (error) {
+                    caughtError = ensureError(error);
+                }
+                return resolve(caughtError);
+            });
+        }
+        else {
+            return result;
+        }
+    }
+    catch (error) {
+        caughtError = ensureError(error);
+    }
+    return caughtError;
+}
+exports.executeAndReturnError = executeAndReturnError;

package/dist/cjs/augments/function.d.ts

@@ -1,3 +1,4 @@
-export type AnyFunction = (...args: any[]) => any;
+export type AnyFunction<ReturnGeneric = any> = (...args: any[]) => ReturnGeneric;
+export type NoInputsFunction<ReturnGeneric = any> = () => ReturnGeneric;
 export declare function isTruthy<T>(input: T): input is NonNullable<T>;
 //# sourceMappingURL=function.d.ts.map

package/dist/cjs/augments/nested-keys.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getValueFromNestedKeys = void 0;
-const error_1 = require("./error");
 const object_1 = require("./object");
 function getValueFromNestedKeys(inputObject, nestedKeys) {
     /**
@@ -10,21 +9,15 @@ function getValueFromNestedKeys(inputObject, nestedKeys) {
      * affect the external API of this function.
      */
     const keyToAccess = nestedKeys[0];
-    try {
-        if (!(0, object_1.typedHasProperty)(inputObject, keyToAccess)) {
-            return undefined;
-        }
-        const currentValue = inputObject[keyToAccess];
-        if (nestedKeys.length > 1) {
-            return getValueFromNestedKeys(currentValue, nestedKeys.slice(1));
-        }
-        else {
-            return currentValue;
-        }
+    if (!(0, object_1.typedHasProperty)(inputObject, keyToAccess)) {
+        return undefined;
     }
-    catch (error) {
-        console.error({ inputObject, nestedKeys });
-        throw new Error(`Failed to traverse into inputObject using key "${String(keyToAccess)}": ${(0, error_1.extractErrorMessage)(error)}`);
+    const currentValue = inputObject[keyToAccess];
+    if (nestedKeys.length > 1) {
+        return getValueFromNestedKeys(currentValue, nestedKeys.slice(1));
+    }
+    else {
+        return currentValue;
     }
 }
 exports.getValueFromNestedKeys = getValueFromNestedKeys;

package/dist/cjs/augments/promise.js

@@ -5,12 +5,11 @@ const error_1 = require("./error");
 const object_1 = require("./object");
 function wait(delayMs) {
     const deferredPromiseWrapper = createDeferredPromiseWrapper();
-    if (delayMs === Infinity || delayMs < 0) {
-        return deferredPromiseWrapper.promise;
+    if (delayMs !== Infinity) {
+        setTimeout(() => {
+            deferredPromiseWrapper.resolve();
+        }, delayMs <= 0 ? 0 : delayMs);
     }
-    setTimeout(() => {
-        deferredPromiseWrapper.resolve();
-    }, delayMs);
     return deferredPromiseWrapper.promise;
 }
 exports.wait = wait;
@@ -57,6 +56,8 @@ function createDeferredPromiseWrapper() {
         resolve = resolveCallback;
         reject = rejectCallback;
     });
+    // no way to test this edge case
+    // istanbul ignore next
     if (!resolve || !reject) {
         throw new Error(`Reject and resolve callbacks were not set by the promise constructor for ${createDeferredPromiseWrapper.name}.`);
     }

package/dist/cjs/augments/truncate-number.d.ts

@@ -0,0 +1,20 @@
+/**
+ * This truncates a number such that is will at a max have 6 characters including suffix, decimal
+ * point, or comma.
+ *
+ * Default suffixes are:
+ *
+ *     'k', // thousand
+ *     'M', // million
+ *     'B', // billion
+ *     'T', // trillion
+ *     'P', // peta-, quadrillion
+ *     'E', // exa- quintillion
+ *     'Z', // zetta- sextillion
+ *     'Y', // yotta- septillion
+ */
+export declare function truncateNumber(originalValue: Readonly<unknown>, { customSuffixes, maxLength, }?: Partial<{
+    customSuffixes: ReadonlyArray<string> | undefined;
+    maxLength: number | undefined;
+}>): string;
+//# sourceMappingURL=truncate-number.d.ts.map

package/dist/cjs/augments/truncate-number.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.truncateNumber = void 0;
+const common_number_1 = require("./common-number");
+const common_string_1 = require("./common-string");
+const regexp_1 = require("./regexp");
+const defaultTruncationSuffixes = [
+    'k',
+    'M',
+    'B',
+    'T',
+    'P',
+    'E',
+    'Z',
+    'Y', // yotta- septillion
+];
+function combineBeforeAndAfterDot({ beforeDot, afterDot = '', maxLength, }) {
+    if (afterDot.length) {
+        const allowedAfterDotLength = maxLength -
+            beforeDot.length -
+            // 1 for the period
+            1;
+        if (allowedAfterDotLength > 0) {
+            const slicedAfterDot = afterDot.slice(0, allowedAfterDotLength);
+            // if slicedAfterDot is just a bunch of 0
+            if (!Number(slicedAfterDot)) {
+                return beforeDot;
+            }
+            return [
+                beforeDot,
+                slicedAfterDot,
+            ].join('.');
+        }
+    }
+    return beforeDot;
+}
+function truncateBigNumber(numberAsString, suffixes, maxLength) {
+    const [beforeDot, afterDot,] = (0, common_string_1.typedSplit)(numberAsString, '.');
+    const withCommas = (0, common_number_1.addCommasToNumber)(beforeDot);
+    const truncationDepth = (0, regexp_1.safeMatch)(withCommas, /,/g).length;
+    const suffix = suffixes[truncationDepth - 1];
+    const [beforeComma, afterComma,] = (0, common_string_1.typedSplit)(withCommas, ',');
+    const trailing = [
+        afterComma,
+        afterDot,
+    ].join('');
+    if (beforeComma.length + 1 > maxLength) {
+        // will look like 0.9M
+        const minimumString = [
+            '0.',
+            beforeComma[0],
+            suffixes[truncationDepth],
+        ].join('');
+        return minimumString;
+    }
+    else {
+        const combined = combineBeforeAndAfterDot({
+            beforeDot: beforeComma,
+            afterDot: trailing,
+            maxLength: maxLength - 1 /* -1 to account for the suffix*/,
+        });
+        return [
+            combined,
+            suffix,
+        ].join('');
+    }
+}
+const minScientificNotationLength = '1e+'.length;
+function truncateScientificNotation({ input, maxLength, }) {
+    const valueString = String(input);
+    const [beforeExponent, rawExponent,] = (0, common_string_1.typedSplit)(valueString, 'e');
+    const exponent = rawExponent.replace(/^[\-\+]/, '');
+    const plusOrMinus = rawExponent[0];
+    const eSuffix = [
+        'e',
+        plusOrMinus,
+        exponent,
+    ].join('');
+    const [beforeDot, afterDot,] = (0, common_string_1.typedSplit)(beforeExponent, '.');
+    const minLength = exponent.length + minScientificNotationLength;
+    if (minLength === maxLength) {
+        // this will look like "4e+4" or "5e-234"
+        return [
+            beforeDot,
+            eSuffix,
+        ].join('');
+    }
+    else if (minLength > maxLength) {
+        // in this case the number is either way too big or way to small for its exponent to fit within the max length so we just jump to 0 or Infinity
+        if (plusOrMinus === '-') {
+            return '0';
+        }
+        else {
+            return String(Infinity);
+        }
+    }
+    else {
+        // in this case we have room to add some decimal values to the number
+        const beforeE = combineBeforeAndAfterDot({
+            afterDot,
+            beforeDot,
+            maxLength: maxLength - exponent.length + minScientificNotationLength,
+        });
+        return [
+            beforeE,
+            eSuffix,
+        ].join('');
+    }
+}
+function handleSmallNumbers(numberAsString, maxLength) {
+    const [beforeDot, afterDot,] = (0, common_string_1.typedSplit)((0, common_number_1.addCommasToNumber)(numberAsString), '.');
+    if (beforeDot.length <= maxLength) {
+        return combineBeforeAndAfterDot({
+            beforeDot,
+            afterDot,
+            maxLength,
+        });
+    }
+    // in this case, the number is not small enough to be handled by this function
+    return undefined;
+}
+/**
+ * This truncates a number such that is will at a max have 6 characters including suffix, decimal
+ * point, or comma.
+ *
+ * Default suffixes are:
+ *
+ *     'k', // thousand
+ *     'M', // million
+ *     'B', // billion
+ *     'T', // trillion
+ *     'P', // peta-, quadrillion
+ *     'E', // exa- quintillion
+ *     'Z', // zetta- sextillion
+ *     'Y', // yotta- septillion
+ */
+function truncateNumber(originalValue, { customSuffixes = defaultTruncationSuffixes, maxLength = 6, } = {}) {
+    const inputNumber = (0, common_number_1.convertIntoNumber)(originalValue);
+    // handle edge cases
+    if (isNaN(inputNumber) || inputNumber === Infinity) {
+        return String(inputNumber);
+    }
+    // handle too big or too small edge cases
+    if ((0, common_number_1.doesRequireScientificNotation)(inputNumber)) {
+        return truncateScientificNotation({ input: inputNumber, maxLength });
+    }
+    const numberAsString = String(inputNumber);
+    const smallResult = handleSmallNumbers(numberAsString, maxLength);
+    if (smallResult != undefined) {
+        return smallResult;
+    }
+    return truncateBigNumber(numberAsString, customSuffixes, maxLength);
+}
+exports.truncateNumber = truncateNumber;

package/dist/cjs/augments/tuple.d.ts

@@ -2,8 +2,8 @@ export type Tuple<ArrayElementGeneric, LengthGeneric extends number> = LengthGen
 type _TupleOf<ArrayElementGeneric, LengthGeneric extends number, FullArrayGeneric extends unknown[]> = FullArrayGeneric['length'] extends LengthGeneric ? FullArrayGeneric : _TupleOf<ArrayElementGeneric, LengthGeneric, [ArrayElementGeneric, ...FullArrayGeneric]>;
 export type AtLeastTuple<ArrayElementGeneric, LengthGeneric extends number> = readonly [
     ...Tuple<ArrayElementGeneric, LengthGeneric>,
-    ...ArrayElementGeneric[]
+    ...(ArrayElementGeneric | undefined)[]
 ];
-export declare function isLengthAtLeast<ArrayElementGeneric, LengthGeneric extends number>(array: ReadonlyArray<ArrayElementGeneric>, length: LengthGeneric): array is AtLeastTuple<ArrayElementGeneric, LengthGeneric>;
+export declare function isLengthAtLeast<ArrayElementGeneric, LengthGeneric extends number>(array: ReadonlyArray<ArrayElementGeneric | undefined>, length: LengthGeneric): array is AtLeastTuple<ArrayElementGeneric, LengthGeneric>;
 export {};
 //# sourceMappingURL=tuple.d.ts.map

package/dist/cjs/index.d.ts

@@ -12,6 +12,7 @@ export * from './augments/object';
 export * from './augments/pick-deep';
 export * from './augments/promise';
 export * from './augments/regexp';
+export * from './augments/truncate-number';
 export * from './augments/tuple';
 export * from './augments/type';
 export * from './augments/type-of';

package/dist/cjs/index.js

@@ -28,6 +28,7 @@ __exportStar(require("./augments/object"), exports);
 __exportStar(require("./augments/pick-deep"), exports);
 __exportStar(require("./augments/promise"), exports);
 __exportStar(require("./augments/regexp"), exports);
+__exportStar(require("./augments/truncate-number"), exports);
 __exportStar(require("./augments/tuple"), exports);
 __exportStar(require("./augments/type"), exports);
 __exportStar(require("./augments/type-of"), exports);

package/dist/esm/augments/common-number.d.ts

@@ -1,4 +1,5 @@
-export declare function addCommasToNumber(input: number): string;
+export declare const NaNString: string;
+export declare function addCommasToNumber(input: number | string): string;
 export declare function clamp(
 /**
  * This uses a destructured object so that consumers cannot get confused as to which input is
@@ -9,25 +10,6 @@ export declare function clamp(
     min: number;
     max: number;
 }): number;
-/**
- * This truncates a number such that is will at a max have 6 characters including suffix, decimal
- * point, or comma.
- *
- * Default suffixes are:
- *
- *     '', // no suffix, numbers below 1000
- *     'k', // thousand
- *     'M', // million
- *     'B', // billion
- *     'T', // trillion
- *     'P', // peta-, quadrillion
- *     'E', // exa- quintillion
- *     'Z', // zetta- sextillion
- *     'Y', // yotta- septillion
- */
-export declare function truncateNumber(originalValue: unknown, { customSuffixes, suppressErrorLogging, customErrorLogCallback, }?: {
-    customSuffixes?: ReadonlyArray<string>;
-    suppressErrorLogging?: boolean;
-    customErrorLogCallback?: (...args: any) => void;
-}): string;
+export declare function convertIntoNumber(input: unknown): number;
+export declare function doesRequireScientificNotation(input: number): boolean;
 //# sourceMappingURL=common-number.d.ts.map

package/dist/esm/augments/common-number.js

@@ -1,6 +1,10 @@
-import { removeCommasFromNumberString, typedSplit } from './common-string';
+import { removeCommasFromNumberString } from './common-string';
 import { safeMatch } from './regexp';
+export const NaNString = String(NaN);
 export function addCommasToNumber(input) {
+    if (typeof input === 'string' && isNaN(Number(input))) {
+        return NaNString;
+    }
     const stringValue = String(input);
     const [digits, decimalValues,] = stringValue.split('.');
     const decimalString = decimalValues ? `.${decimalValues}` : '';
@@ -18,88 +22,17 @@ export function clamp(
 { value, min, max, }) {
     return Math.max(Math.min(value, max), min);
 }
-const defaultTruncationSuffixes = [
-    '',
-    'k',
-    'M',
-    'B',
-    'T',
-    'P',
-    'E',
-    'Z',
-    'Y', // yotta- septillion
-];
-function recursiveTruncation(value, recursionDepth = 0, decimalValues = '') {
-    var _a;
-    if (value.includes('e+')) {
-        throw new Error(`Number is too large, it cannot be truncated: ${value}`);
+export function convertIntoNumber(input) {
+    if (typeof input === 'number') {
+        return input;
     }
-    else if (value.includes('e-')) {
-        throw new Error(`Number is too small, it cannot be truncated: ${value}`);
+    else if (typeof input === 'string') {
+        return Number(removeCommasFromNumberString(input));
     }
-    const split = typedSplit(value, '.');
-    decimalValues = (_a = split[1]) !== null && _a !== void 0 ? _a : decimalValues;
-    const amount = split[0];
-    if (amount.length > 3) {
-        decimalValues = amount.slice(-3);
-        return recursiveTruncation(amount.slice(0, -3), recursionDepth + 1, decimalValues);
+    else {
+        return Number(input);
     }
-    return {
-        value: amount,
-        decimalValues,
-        recursionDepth,
-    };
 }
-const maxDecimals = 4;
-/**
- * This truncates a number such that is will at a max have 6 characters including suffix, decimal
- * point, or comma.
- *
- * Default suffixes are:
- *
- *     '', // no suffix, numbers below 1000
- *     'k', // thousand
- *     'M', // million
- *     'B', // billion
- *     'T', // trillion
- *     'P', // peta-, quadrillion
- *     'E', // exa- quintillion
- *     'Z', // zetta- sextillion
- *     'Y', // yotta- septillion
- */
-export function truncateNumber(originalValue, { customSuffixes, suppressErrorLogging, customErrorLogCallback, } = {}) {
-    try {
-        const value = typeof originalValue === 'number'
-            ? originalValue
-            : typeof originalValue === 'string'
-                ? Number(removeCommasFromNumberString(originalValue))
-                : Number(originalValue);
-        if (isNaN(value)) {
-            throw new Error(`${originalValue} could not be converted into a number.`);
-        }
-        const stringValue = String(value);
-        const results = recursiveTruncation(stringValue);
-        const suffixes = customSuffixes !== null && customSuffixes !== void 0 ? customSuffixes : defaultTruncationSuffixes;
-        const suffix = suffixes[results.recursionDepth];
-        if (suffix === undefined) {
-            throw new Error(`Number is too large, could not truncate: ${value}`);
-        }
-        const decimalPlaces = maxDecimals - (results.value.length - 1) - suffix.length;
-        const decimalValues = results.decimalValues.replace(/0+$/, '').slice(0, decimalPlaces);
-        const withDecimal = decimalValues.length ? `.${decimalValues}` : '';
-        const combined = `${results.value}${withDecimal}${suffix}`;
-        if (combined.length > stringValue.length + 1) {
-            return addCommasToNumber(value);
-        }
-        else {
-            return combined;
-        }
-    }
-    catch (error) {
-        const errorCallback = customErrorLogCallback ? customErrorLogCallback : console.error;
-        if (!suppressErrorLogging) {
-            errorCallback(error);
-        }
-        return String(originalValue);
-    }
+export function doesRequireScientificNotation(input) {
+    return String(input).includes('e');
 }

package/dist/esm/augments/error.d.ts

@@ -1,4 +1,6 @@
+import { NoInputsFunction } from './function';
 import { AtLeastTuple } from './tuple';
+import { UnPromise } from './type';
 export declare function combineErrors(errors: AtLeastTuple<Error, 1>): Error;
 export declare function combineErrors(errors: ReadonlyArray<never>): undefined;
 export declare function combineErrors(errors: ReadonlyArray<Error>): Error | undefined;
@@ -6,4 +8,6 @@ export declare function combineErrors(errors?: undefined): undefined;
 export declare function combineErrorMessages(errors?: ReadonlyArray<Error | string | undefined> | undefined): string;
 export declare function extractErrorMessage(error: unknown): string;
 export declare function ensureError(input: unknown): Error;
+export declare function executeAndReturnError<CallbackGeneric extends NoInputsFunction<PromiseLike<any>>>(callback: CallbackGeneric): Promise<Error | UnPromise<ReturnType<CallbackGeneric>>>;
+export declare function executeAndReturnError<CallbackGeneric extends NoInputsFunction>(callback: CallbackGeneric): Error | ReturnType<CallbackGeneric>;
 //# sourceMappingURL=error.d.ts.map

package/dist/esm/augments/error.js

@@ -1,4 +1,5 @@
 import { isTruthy } from './function';
+import { isPromiseLike } from './promise';
 export function combineErrors(errors) {
     if (!errors || errors.length === 0) {
         return undefined;
@@ -34,3 +35,28 @@ export function ensureError(input) {
         return new Error(extractErrorMessage(input));
     }
 }
+export function executeAndReturnError(callback) {
+    let caughtError;
+    try {
+        const result = callback();
+        if (isPromiseLike(result)) {
+            return new Promise(async (resolve) => {
+                try {
+                    const output = await result;
+                    return resolve(output);
+                }
+                catch (error) {
+                    caughtError = ensureError(error);
+                }
+                return resolve(caughtError);
+            });
+        }
+        else {
+            return result;
+        }
+    }
+    catch (error) {
+        caughtError = ensureError(error);
+    }
+    return caughtError;
+}

package/dist/esm/augments/function.d.ts

@@ -1,3 +1,4 @@
-export type AnyFunction = (...args: any[]) => any;
+export type AnyFunction<ReturnGeneric = any> = (...args: any[]) => ReturnGeneric;
+export type NoInputsFunction<ReturnGeneric = any> = () => ReturnGeneric;
 export declare function isTruthy<T>(input: T): input is NonNullable<T>;
 //# sourceMappingURL=function.d.ts.map

package/dist/esm/augments/nested-keys.js

@@ -1,4 +1,3 @@
-import { extractErrorMessage } from './error';
 import { typedHasProperty } from './object';
 export function getValueFromNestedKeys(inputObject, nestedKeys) {
     /**
@@ -7,20 +6,14 @@ export function getValueFromNestedKeys(inputObject, nestedKeys) {
      * affect the external API of this function.
      */
     const keyToAccess = nestedKeys[0];
-    try {
-        if (!typedHasProperty(inputObject, keyToAccess)) {
-            return undefined;
-        }
-        const currentValue = inputObject[keyToAccess];
-        if (nestedKeys.length > 1) {
-            return getValueFromNestedKeys(currentValue, nestedKeys.slice(1));
-        }
-        else {
-            return currentValue;
-        }
+    if (!typedHasProperty(inputObject, keyToAccess)) {
+        return undefined;
     }
-    catch (error) {
-        console.error({ inputObject, nestedKeys });
-        throw new Error(`Failed to traverse into inputObject using key "${String(keyToAccess)}": ${extractErrorMessage(error)}`);
+    const currentValue = inputObject[keyToAccess];
+    if (nestedKeys.length > 1) {
+        return getValueFromNestedKeys(currentValue, nestedKeys.slice(1));
+    }
+    else {
+        return currentValue;
     }
 }

package/dist/esm/augments/promise.js

@@ -2,12 +2,11 @@ import { extractErrorMessage } from './error';
 import { typedHasProperty } from './object';
 export function wait(delayMs) {
     const deferredPromiseWrapper = createDeferredPromiseWrapper();
-    if (delayMs === Infinity || delayMs < 0) {
-        return deferredPromiseWrapper.promise;
+    if (delayMs !== Infinity) {
+        setTimeout(() => {
+            deferredPromiseWrapper.resolve();
+        }, delayMs <= 0 ? 0 : delayMs);
     }
-    setTimeout(() => {
-        deferredPromiseWrapper.resolve();
-    }, delayMs);
     return deferredPromiseWrapper.promise;
 }
 export function isPromiseLike(input) {
@@ -50,6 +49,8 @@ export function createDeferredPromiseWrapper() {
         resolve = resolveCallback;
         reject = rejectCallback;
     });
+    // no way to test this edge case
+    // istanbul ignore next
     if (!resolve || !reject) {
         throw new Error(`Reject and resolve callbacks were not set by the promise constructor for ${createDeferredPromiseWrapper.name}.`);
     }

package/dist/esm/augments/truncate-number.d.ts

@@ -0,0 +1,20 @@
+/**
+ * This truncates a number such that is will at a max have 6 characters including suffix, decimal
+ * point, or comma.
+ *
+ * Default suffixes are:
+ *
+ *     'k', // thousand
+ *     'M', // million
+ *     'B', // billion
+ *     'T', // trillion
+ *     'P', // peta-, quadrillion
+ *     'E', // exa- quintillion
+ *     'Z', // zetta- sextillion
+ *     'Y', // yotta- septillion
+ */
+export declare function truncateNumber(originalValue: Readonly<unknown>, { customSuffixes, maxLength, }?: Partial<{
+    customSuffixes: ReadonlyArray<string> | undefined;
+    maxLength: number | undefined;
+}>): string;
+//# sourceMappingURL=truncate-number.d.ts.map

package/dist/esm/augments/truncate-number.js

@@ -0,0 +1,150 @@
+import { addCommasToNumber, convertIntoNumber, doesRequireScientificNotation } from './common-number';
+import { typedSplit } from './common-string';
+import { safeMatch } from './regexp';
+const defaultTruncationSuffixes = [
+    'k',
+    'M',
+    'B',
+    'T',
+    'P',
+    'E',
+    'Z',
+    'Y', // yotta- septillion
+];
+function combineBeforeAndAfterDot({ beforeDot, afterDot = '', maxLength, }) {
+    if (afterDot.length) {
+        const allowedAfterDotLength = maxLength -
+            beforeDot.length -
+            // 1 for the period
+            1;
+        if (allowedAfterDotLength > 0) {
+            const slicedAfterDot = afterDot.slice(0, allowedAfterDotLength);
+            // if slicedAfterDot is just a bunch of 0
+            if (!Number(slicedAfterDot)) {
+                return beforeDot;
+            }
+            return [
+                beforeDot,
+                slicedAfterDot,
+            ].join('.');
+        }
+    }
+    return beforeDot;
+}
+function truncateBigNumber(numberAsString, suffixes, maxLength) {
+    const [beforeDot, afterDot,] = typedSplit(numberAsString, '.');
+    const withCommas = addCommasToNumber(beforeDot);
+    const truncationDepth = safeMatch(withCommas, /,/g).length;
+    const suffix = suffixes[truncationDepth - 1];
+    const [beforeComma, afterComma,] = typedSplit(withCommas, ',');
+    const trailing = [
+        afterComma,
+        afterDot,
+    ].join('');
+    if (beforeComma.length + 1 > maxLength) {
+        // will look like 0.9M
+        const minimumString = [
+            '0.',
+            beforeComma[0],
+            suffixes[truncationDepth],
+        ].join('');
+        return minimumString;
+    }
+    else {
+        const combined = combineBeforeAndAfterDot({
+            beforeDot: beforeComma,
+            afterDot: trailing,
+            maxLength: maxLength - 1 /* -1 to account for the suffix*/,
+        });
+        return [
+            combined,
+            suffix,
+        ].join('');
+    }
+}
+const minScientificNotationLength = '1e+'.length;
+function truncateScientificNotation({ input, maxLength, }) {
+    const valueString = String(input);
+    const [beforeExponent, rawExponent,] = typedSplit(valueString, 'e');
+    const exponent = rawExponent.replace(/^[\-\+]/, '');
+    const plusOrMinus = rawExponent[0];
+    const eSuffix = [
+        'e',
+        plusOrMinus,
+        exponent,
+    ].join('');
+    const [beforeDot, afterDot,] = typedSplit(beforeExponent, '.');
+    const minLength = exponent.length + minScientificNotationLength;
+    if (minLength === maxLength) {
+        // this will look like "4e+4" or "5e-234"
+        return [
+            beforeDot,
+            eSuffix,
+        ].join('');
+    }
+    else if (minLength > maxLength) {
+        // in this case the number is either way too big or way to small for its exponent to fit within the max length so we just jump to 0 or Infinity
+        if (plusOrMinus === '-') {
+            return '0';
+        }
+        else {
+            return String(Infinity);
+        }
+    }
+    else {
+        // in this case we have room to add some decimal values to the number
+        const beforeE = combineBeforeAndAfterDot({
+            afterDot,
+            beforeDot,
+            maxLength: maxLength - exponent.length + minScientificNotationLength,
+        });
+        return [
+            beforeE,
+            eSuffix,
+        ].join('');
+    }
+}
+function handleSmallNumbers(numberAsString, maxLength) {
+    const [beforeDot, afterDot,] = typedSplit(addCommasToNumber(numberAsString), '.');
+    if (beforeDot.length <= maxLength) {
+        return combineBeforeAndAfterDot({
+            beforeDot,
+            afterDot,
+            maxLength,
+        });
+    }
+    // in this case, the number is not small enough to be handled by this function
+    return undefined;
+}
+/**
+ * This truncates a number such that is will at a max have 6 characters including suffix, decimal
+ * point, or comma.
+ *
+ * Default suffixes are:
+ *
+ *     'k', // thousand
+ *     'M', // million
+ *     'B', // billion
+ *     'T', // trillion
+ *     'P', // peta-, quadrillion
+ *     'E', // exa- quintillion
+ *     'Z', // zetta- sextillion
+ *     'Y', // yotta- septillion
+ */
+export function truncateNumber(originalValue, { customSuffixes = defaultTruncationSuffixes, maxLength = 6, } = {}) {
+    const inputNumber = convertIntoNumber(originalValue);
+    // handle edge cases
+    if (isNaN(inputNumber) || inputNumber === Infinity) {
+        return String(inputNumber);
+    }
+    // handle too big or too small edge cases
+    if (doesRequireScientificNotation(inputNumber)) {
+        return truncateScientificNotation({ input: inputNumber, maxLength });
+    }
+    const numberAsString = String(inputNumber);
+    const smallResult = handleSmallNumbers(numberAsString, maxLength);
+    if (smallResult != undefined) {
+        return smallResult;
+    }
+    return truncateBigNumber(numberAsString, customSuffixes, maxLength);
+}

package/dist/esm/augments/tuple.d.ts

@@ -2,8 +2,8 @@ export type Tuple<ArrayElementGeneric, LengthGeneric extends number> = LengthGen
 type _TupleOf<ArrayElementGeneric, LengthGeneric extends number, FullArrayGeneric extends unknown[]> = FullArrayGeneric['length'] extends LengthGeneric ? FullArrayGeneric : _TupleOf<ArrayElementGeneric, LengthGeneric, [ArrayElementGeneric, ...FullArrayGeneric]>;
 export type AtLeastTuple<ArrayElementGeneric, LengthGeneric extends number> = readonly [
     ...Tuple<ArrayElementGeneric, LengthGeneric>,
-    ...ArrayElementGeneric[]
+    ...(ArrayElementGeneric | undefined)[]
 ];
-export declare function isLengthAtLeast<ArrayElementGeneric, LengthGeneric extends number>(array: ReadonlyArray<ArrayElementGeneric>, length: LengthGeneric): array is AtLeastTuple<ArrayElementGeneric, LengthGeneric>;
+export declare function isLengthAtLeast<ArrayElementGeneric, LengthGeneric extends number>(array: ReadonlyArray<ArrayElementGeneric | undefined>, length: LengthGeneric): array is AtLeastTuple<ArrayElementGeneric, LengthGeneric>;
 export {};
 //# sourceMappingURL=tuple.d.ts.map

package/dist/esm/index.d.ts

@@ -12,6 +12,7 @@ export * from './augments/object';
 export * from './augments/pick-deep';
 export * from './augments/promise';
 export * from './augments/regexp';
+export * from './augments/truncate-number';
 export * from './augments/tuple';
 export * from './augments/type';
 export * from './augments/type-of';

package/dist/esm/index.js

@@ -12,6 +12,7 @@ export * from './augments/object';
 export * from './augments/pick-deep';
 export * from './augments/promise';
 export * from './augments/regexp';
+export * from './augments/truncate-number';
 export * from './augments/tuple';
 export * from './augments/type';
 export * from './augments/type-of';

package/dist/types/augments/common-number.d.ts

@@ -1,4 +1,5 @@
-export declare function addCommasToNumber(input: number): string;
+export declare const NaNString: string;
+export declare function addCommasToNumber(input: number | string): string;
 export declare function clamp(
 /**
  * This uses a destructured object so that consumers cannot get confused as to which input is
@@ -9,25 +10,6 @@ export declare function clamp(
     min: number;
     max: number;
 }): number;
-/**
- * This truncates a number such that is will at a max have 6 characters including suffix, decimal
- * point, or comma.
- *
- * Default suffixes are:
- *
- *     '', // no suffix, numbers below 1000
- *     'k', // thousand
- *     'M', // million
- *     'B', // billion
- *     'T', // trillion
- *     'P', // peta-, quadrillion
- *     'E', // exa- quintillion
- *     'Z', // zetta- sextillion
- *     'Y', // yotta- septillion
- */
-export declare function truncateNumber(originalValue: unknown, { customSuffixes, suppressErrorLogging, customErrorLogCallback, }?: {
-    customSuffixes?: ReadonlyArray<string>;
-    suppressErrorLogging?: boolean;
-    customErrorLogCallback?: (...args: any) => void;
-}): string;
+export declare function convertIntoNumber(input: unknown): number;
+export declare function doesRequireScientificNotation(input: number): boolean;
 //# sourceMappingURL=common-number.d.ts.map

package/dist/types/augments/error.d.ts

@@ -1,4 +1,6 @@
+import { NoInputsFunction } from './function';
 import { AtLeastTuple } from './tuple';
+import { UnPromise } from './type';
 export declare function combineErrors(errors: AtLeastTuple<Error, 1>): Error;
 export declare function combineErrors(errors: ReadonlyArray<never>): undefined;
 export declare function combineErrors(errors: ReadonlyArray<Error>): Error | undefined;
@@ -6,4 +8,6 @@ export declare function combineErrors(errors?: undefined): undefined;
 export declare function combineErrorMessages(errors?: ReadonlyArray<Error | string | undefined> | undefined): string;
 export declare function extractErrorMessage(error: unknown): string;
 export declare function ensureError(input: unknown): Error;
+export declare function executeAndReturnError<CallbackGeneric extends NoInputsFunction<PromiseLike<any>>>(callback: CallbackGeneric): Promise<Error | UnPromise<ReturnType<CallbackGeneric>>>;
+export declare function executeAndReturnError<CallbackGeneric extends NoInputsFunction>(callback: CallbackGeneric): Error | ReturnType<CallbackGeneric>;
 //# sourceMappingURL=error.d.ts.map

package/dist/types/augments/function.d.ts

@@ -1,3 +1,4 @@
-export type AnyFunction = (...args: any[]) => any;
+export type AnyFunction<ReturnGeneric = any> = (...args: any[]) => ReturnGeneric;
+export type NoInputsFunction<ReturnGeneric = any> = () => ReturnGeneric;
 export declare function isTruthy<T>(input: T): input is NonNullable<T>;
 //# sourceMappingURL=function.d.ts.map

package/dist/types/augments/truncate-number.d.ts

@@ -0,0 +1,20 @@
+/**
+ * This truncates a number such that is will at a max have 6 characters including suffix, decimal
+ * point, or comma.
+ *
+ * Default suffixes are:
+ *
+ *     'k', // thousand
+ *     'M', // million
+ *     'B', // billion
+ *     'T', // trillion
+ *     'P', // peta-, quadrillion
+ *     'E', // exa- quintillion
+ *     'Z', // zetta- sextillion
+ *     'Y', // yotta- septillion
+ */
+export declare function truncateNumber(originalValue: Readonly<unknown>, { customSuffixes, maxLength, }?: Partial<{
+    customSuffixes: ReadonlyArray<string> | undefined;
+    maxLength: number | undefined;
+}>): string;
+//# sourceMappingURL=truncate-number.d.ts.map

package/dist/types/augments/tuple.d.ts

@@ -2,8 +2,8 @@ export type Tuple<ArrayElementGeneric, LengthGeneric extends number> = LengthGen
 type _TupleOf<ArrayElementGeneric, LengthGeneric extends number, FullArrayGeneric extends unknown[]> = FullArrayGeneric['length'] extends LengthGeneric ? FullArrayGeneric : _TupleOf<ArrayElementGeneric, LengthGeneric, [ArrayElementGeneric, ...FullArrayGeneric]>;
 export type AtLeastTuple<ArrayElementGeneric, LengthGeneric extends number> = readonly [
     ...Tuple<ArrayElementGeneric, LengthGeneric>,
-    ...ArrayElementGeneric[]
+    ...(ArrayElementGeneric | undefined)[]
 ];
-export declare function isLengthAtLeast<ArrayElementGeneric, LengthGeneric extends number>(array: ReadonlyArray<ArrayElementGeneric>, length: LengthGeneric): array is AtLeastTuple<ArrayElementGeneric, LengthGeneric>;
+export declare function isLengthAtLeast<ArrayElementGeneric, LengthGeneric extends number>(array: ReadonlyArray<ArrayElementGeneric | undefined>, length: LengthGeneric): array is AtLeastTuple<ArrayElementGeneric, LengthGeneric>;
 export {};
 //# sourceMappingURL=tuple.d.ts.map

package/dist/types/index.d.ts

@@ -12,6 +12,7 @@ export * from './augments/object';
 export * from './augments/pick-deep';
 export * from './augments/promise';
 export * from './augments/regexp';
+export * from './augments/truncate-number';
 export * from './augments/tuple';
 export * from './augments/type';
 export * from './augments/type-of';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/common",
-    "version": "6.4.0",
+    "version": "7.0.0",
     "homepage": "https://github.com/electrovir/augment-vir/tree/main/packages/common",
     "bugs": {
         "url": "https://github.com/electrovir/augment-vir/issues"
@@ -23,7 +23,7 @@
         "test:coverage": "npm test"
     },
     "dependencies": {
-        "type-fest": "^3.5.0"
+        "type-fest": "^3.5.1"
     },
     "devDependencies": {
         "typescript": "^4.9.4"