@augment-vir/common 28.0.2 → 28.1.0

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.clamp = exports.round = exports.wrapNumber = exports.toEnsuredNumber = exports.ensureMinAndMax = exports.doesRequireScientificNotation = exports.convertIntoNumber = exports.addCommasToNumber = exports.NaNString = void 0;
+exports.clamp = exports.round = exports.wrapNumber = exports.toMaybeNumber = exports.toEnsuredNumber = exports.convertIntoNumber = exports.toNumber = exports.ensureMinAndMax = exports.doesRequireScientificNotation = exports.addCommasToNumber = exports.NaNString = void 0;
 const common_string_1 = require("./common-string");
 const regexp_1 = require("./regexp");
 exports.NaNString = String(NaN);
@@ -25,18 +25,6 @@ function addCommasToNumber(input) {
     ].join('');
 }
 exports.addCommasToNumber = addCommasToNumber;
-function convertIntoNumber(input) {
-    if (typeof input === 'number') {
-        return input;
-    }
-    else if (typeof input === 'string') {
-        return Number((0, common_string_1.removeCommasFromNumberString)(input));
-    }
-    else {
-        return Number(input);
-    }
-}
-exports.convertIntoNumber = convertIntoNumber;
 function doesRequireScientificNotation(input) {
     return String(input).includes('e');
 }
@@ -54,16 +42,46 @@ function ensureMinAndMax({ min, max }) {
     }
 }
 exports.ensureMinAndMax = ensureMinAndMax;
+/**
+ * Tries to convert the input into a number. Handles strings with commas. Note: this might return
+ * `NaN`.
+ */
+function toNumber(input) {
+    if (typeof input === 'number') {
+        return input;
+    }
+    else if (typeof input === 'string') {
+        return Number((0, common_string_1.removeCommasFromNumberString)(input));
+    }
+    else {
+        return Number(input);
+    }
+}
+exports.toNumber = toNumber;
+/** @deprecated Use {@link toNumber} instead. */
+exports.convertIntoNumber = toNumber;
+/** Tries to convert the input into a number and throws an error if `NaN` is created. */
 function toEnsuredNumber(input) {
-    const numeric = Number(input);
-    if (isNaN(numeric)) {
-        throw new Error(`Cannot convert given input to a number: ${input}`);
+    const numeric = toMaybeNumber(input);
+    if (numeric == undefined) {
+        throw new Error(`Cannot convert to a number: ${input}`);
     }
     else {
         return numeric;
     }
 }
 exports.toEnsuredNumber = toEnsuredNumber;
+/** Tries to convert the input into a number and returns `undefined` if `NaN` is created. */
+function toMaybeNumber(input) {
+    const numeric = toNumber(input);
+    if (isNaN(numeric)) {
+        return undefined;
+    }
+    else {
+        return numeric;
+    }
+}
+exports.toMaybeNumber = toMaybeNumber;
 /**
  * If the given value is outside the given min/max bounds, instead of clamping the number (as the
  * `clamp` function does), this function wraps the value around to the next bound.

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.typedSplit = exports.getAllIndexesOf = exports.escapeStringForRegExp = exports.replaceStringAtIndex = exports.camelCaseToKebabCase = exports.isCase = exports.hasCase = exports.StringCaseEnum = exports.kebabCaseToCamelCase = exports.capitalizeFirstLetter = exports.splitIncludeSplit = exports.collapseWhiteSpace = exports.removeCommasFromNumberString = exports.removeColor = exports.removeAnsiEscapeCodes = exports.joinWithFinalConjunction = void 0;
+exports.typedSplit = exports.getAllIndexesOf = exports.escapeStringForRegExp = exports.replaceStringAtIndex = exports.camelCaseToKebabCase = exports.isCase = exports.hasCase = exports.StringCaseEnum = exports.kebabCaseToCamelCase = exports.capitalizeFirstLetter = exports.splitIncludeSplit = exports.collapseWhiteSpace = exports.removeCommasFromNumberString = exports.removeColor = exports.removeAnsiEscapeCodes = exports.wrapString = exports.joinWithFinalConjunction = void 0;
 const ansi_1 = require("./ansi");
 const regexp_1 = require("./regexp");
 /**
@@ -28,6 +28,14 @@ function joinWithFinalConjunction(list, conjunction = 'and') {
     return fullyJoined;
 }
 exports.joinWithFinalConjunction = joinWithFinalConjunction;
+/** Wraps `value` on both sides with `wrapper`. */
+function wrapString({ value, wrapper }) {
+    return [
+        wrapper,
+        wrapper,
+    ].join(value);
+}
+exports.wrapString = wrapString;
 function removeAnsiEscapeCodes(input) {
     return input.replace(ansi_1.ansiRegex, '');
 }

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

@@ -21,17 +21,6 @@ export function addCommasToNumber(input) {
         decimalString,
     ].join('');
 }
-export function convertIntoNumber(input) {
-    if (typeof input === 'number') {
-        return input;
-    }
-    else if (typeof input === 'string') {
-        return Number(removeCommasFromNumberString(input));
-    }
-    else {
-        return Number(input);
-    }
-}
 export function doesRequireScientificNotation(input) {
     return String(input).includes('e');
 }
@@ -47,10 +36,38 @@ export function ensureMinAndMax({ min, max }) {
         return { min, max };
     }
 }
+/**
+ * Tries to convert the input into a number. Handles strings with commas. Note: this might return
+ * `NaN`.
+ */
+export function toNumber(input) {
+    if (typeof input === 'number') {
+        return input;
+    }
+    else if (typeof input === 'string') {
+        return Number(removeCommasFromNumberString(input));
+    }
+    else {
+        return Number(input);
+    }
+}
+/** @deprecated Use {@link toNumber} instead. */
+export const convertIntoNumber = toNumber;
+/** Tries to convert the input into a number and throws an error if `NaN` is created. */
 export function toEnsuredNumber(input) {
-    const numeric = Number(input);
+    const numeric = toMaybeNumber(input);
+    if (numeric == undefined) {
+        throw new Error(`Cannot convert to a number: ${input}`);
+    }
+    else {
+        return numeric;
+    }
+}
+/** Tries to convert the input into a number and returns `undefined` if `NaN` is created. */
+export function toMaybeNumber(input) {
+    const numeric = toNumber(input);
     if (isNaN(numeric)) {
-        throw new Error(`Cannot convert given input to a number: ${input}`);
+        return undefined;
     }
     else {
         return numeric;

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

@@ -24,6 +24,13 @@ export function joinWithFinalConjunction(list, conjunction = 'and') {
     const fullyJoined = `${commaJoined}${commaSep}${conjunction} ${list[list.length - 1]}`;
     return fullyJoined;
 }
+/** Wraps `value` on both sides with `wrapper`. */
+export function wrapString({ value, wrapper }) {
+    return [
+        wrapper,
+        wrapper,
+    ].join(value);
+}
 export function removeAnsiEscapeCodes(input) {
     return input.replace(ansiRegex, '');
 }

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

@@ -1,6 +1,5 @@
 export declare const NaNString: string;
 export declare function addCommasToNumber(input: number | string): string;
-export declare function convertIntoNumber(input: unknown): number;
 export declare function doesRequireScientificNotation(input: number): boolean;
 /**
  * Given a min and max, ensures that they are in correct order. Meaning, min is less than max. If
@@ -13,7 +12,17 @@ export declare function ensureMinAndMax({ min, max }: {
     min: number;
     max: number;
 };
-export declare function toEnsuredNumber(input: any): number;
+/**
+ * Tries to convert the input into a number. Handles strings with commas. Note: this might return
+ * `NaN`.
+ */
+export declare function toNumber(input: unknown): number;
+/** @deprecated Use {@link toNumber} instead. */
+export declare const convertIntoNumber: typeof toNumber;
+/** Tries to convert the input into a number and throws an error if `NaN` is created. */
+export declare function toEnsuredNumber(input: unknown): number;
+/** Tries to convert the input into a number and returns `undefined` if `NaN` is created. */
+export declare function toMaybeNumber(input: unknown): number | undefined;
 /**
  * If the given value is outside the given min/max bounds, instead of clamping the number (as the
  * `clamp` function does), this function wraps the value around to the next bound.

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

@@ -10,6 +10,11 @@ import { AtLeastTuple } from './tuple';
  * @param conjunction Defaults to 'and'. The conjunction to be used before the final element.
  */
 export declare function joinWithFinalConjunction(list: ReadonlyArray<any>, conjunction?: string): string;
+/** Wraps `value` on both sides with `wrapper`. */
+export declare function wrapString({ value, wrapper }: {
+    value: string;
+    wrapper: string;
+}): string;
 export declare function removeAnsiEscapeCodes(input: string): string;
 export declare const removeColor: typeof removeAnsiEscapeCodes;
 export declare function removeCommasFromNumberString(numberString: string): string;

package/dist/types/augments/wrap-in-try.d.ts

@@ -13,11 +13,11 @@ export type WrapInTryOptions<FallbackValue> = PartialAndUndefined<{
     fallbackValue: FallbackValue;
 }>;
 export declare function wrapInTry<Value extends Promise<any>>(callback: NoInputsFunction<Value>, options?: undefined | {
-    handleError?: undefined;
+    handleError?: never;
     fallbackValue?: never;
 }): Promise<Error | Awaited<Value>>;
 export declare function wrapInTry<Value>(callback: NoInputsFunction<Value>, options?: undefined | {
-    handleError?: undefined;
+    handleError?: never;
     fallbackValue?: never;
 }): Error | Value;
 export declare function wrapInTry<Value extends Promise<any>, FallbackValue = undefined>(callback: NoInputsFunction<Value>, options: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/common",
-    "version": "28.0.2",
+    "version": "28.1.0",
     "homepage": "https://github.com/electrovir/augment-vir/tree/main/packages/common",
     "bugs": {
         "url": "https://github.com/electrovir/augment-vir/issues"