@augment-vir/common 31.71.4 → 31.72.0

package/dist/augments/convert/convert-to.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A suite of functions that each convert an `unknown` value into a specific type, throwing an error
+ * if the conversion is not possible.
+ *
+ * @category Convert
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {convertTo} from '@augment-vir/common';
+ *
+ * convertTo.string(42); // `'42'`
+ * convertTo.string(undefined); // throws an error
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare const convertTo: {
+    /**
+     * Converts anything into a string.
+     *
+     * @example
+     *
+     * ```ts
+     * import {convertTo} from '@augment-vir/common';
+     *
+     * convertTo.string('hi'); // `'hi'`
+     * convertTo.string(42); // `'42'`
+     * convertTo.string(null); // `'hi'`
+     * convertTo.string({}); // `'{}'`
+     * ```
+     */
+    string(this: void, value: unknown): string;
+    /**
+     * Converts almost anything into a string but maps `null`, `undefined`, and empty string results
+     * to `undefined`.
+     *
+     * @example
+     *
+     * ```ts
+     * import {convertTo} from '@augment-vir/common';
+     *
+     * convertTo.string('hi'); // `'hi'`
+     * convertTo.string(42); // `'42'`
+     * convertTo.string(null); // `undefined`
+     * convertTo.string(''); // `undefined`
+     * convertTo.string({}); // `'{}'`
+     * ```
+     */
+    maybeString(this: void, value: unknown): string | undefined;
+    /**
+     * Converts almost anything into a number but maps `null`, `undefined`, and any conversion that
+     * results in `NaN` to `undefined`.
+     *
+     * @example
+     *
+     * ```ts
+     * import {convertTo} from '@augment-vir/common';
+     *
+     * convertTo.maybeNumber('42'); // `42`
+     * convertTo.maybeNumber(42); // `42`
+     * convertTo.maybeNumber(null); // `undefined`
+     * convertTo.maybeNumber('hello'); // `undefined`
+     * ```
+     */
+    maybeNumber(this: void, value: unknown): number | undefined;
+};

package/dist/augments/convert/convert-to.js

@@ -0,0 +1,90 @@
+import { isPrimitive, stringify } from '@augment-vir/core';
+/**
+ * A suite of functions that each convert an `unknown` value into a specific type, throwing an error
+ * if the conversion is not possible.
+ *
+ * @category Convert
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {convertTo} from '@augment-vir/common';
+ *
+ * convertTo.string(42); // `'42'`
+ * convertTo.string(undefined); // throws an error
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export const convertTo = {
+    /**
+     * Converts anything into a string.
+     *
+     * @example
+     *
+     * ```ts
+     * import {convertTo} from '@augment-vir/common';
+     *
+     * convertTo.string('hi'); // `'hi'`
+     * convertTo.string(42); // `'42'`
+     * convertTo.string(null); // `'hi'`
+     * convertTo.string({}); // `'{}'`
+     * ```
+     */
+    string(value) {
+        if (isPrimitive(value)) {
+            return String(value);
+        }
+        else {
+            return stringify(value);
+        }
+    },
+    /**
+     * Converts almost anything into a string but maps `null`, `undefined`, and empty string results
+     * to `undefined`.
+     *
+     * @example
+     *
+     * ```ts
+     * import {convertTo} from '@augment-vir/common';
+     *
+     * convertTo.string('hi'); // `'hi'`
+     * convertTo.string(42); // `'42'`
+     * convertTo.string(null); // `undefined`
+     * convertTo.string(''); // `undefined`
+     * convertTo.string({}); // `'{}'`
+     * ```
+     */
+    maybeString(value) {
+        if (value == undefined) {
+            return undefined;
+        }
+        else {
+            return convertTo.string(value) || undefined;
+        }
+    },
+    /**
+     * Converts almost anything into a number but maps `null`, `undefined`, and any conversion that
+     * results in `NaN` to `undefined`.
+     *
+     * @example
+     *
+     * ```ts
+     * import {convertTo} from '@augment-vir/common';
+     *
+     * convertTo.maybeNumber('42'); // `42`
+     * convertTo.maybeNumber(42); // `42`
+     * convertTo.maybeNumber(null); // `undefined`
+     * convertTo.maybeNumber('hello'); // `undefined`
+     * ```
+     */
+    maybeNumber(value) {
+        if (value == undefined || value === '') {
+            return undefined;
+        }
+        else {
+            const converted = Number(value);
+            return Number.isNaN(converted) ? undefined : converted;
+        }
+    },
+};

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from './augments/array/from-async-iterable.js';
 export * from './augments/array/repeat-array.js';
 export * from './augments/array/shuffle-array.js';
 export * from './augments/array/string-array.js';
+export * from './augments/convert/convert-to.js';
 export * from './augments/core-exports.js';
 export * from './augments/enum/enum-value-check.js';
 export * from './augments/error/combine-errors.js';

package/dist/index.js

@@ -14,6 +14,7 @@ export * from './augments/array/from-async-iterable.js';
 export * from './augments/array/repeat-array.js';
 export * from './augments/array/shuffle-array.js';
 export * from './augments/array/string-array.js';
+export * from './augments/convert/convert-to.js';
 export * from './augments/core-exports.js';
 export * from './augments/enum/enum-value-check.js';
 export * from './augments/error/combine-errors.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/common",
-    "version": "31.71.4",
+    "version": "31.72.0",
     "description": "A collection of augments, helpers types, functions, and classes for any JavaScript environment.",
     "keywords": [
         "augment",
@@ -40,8 +40,8 @@
         "test:web": "virmator --no-deps test web"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.71.4",
-        "@augment-vir/core": "^31.71.4",
+        "@augment-vir/assert": "^31.72.0",
+        "@augment-vir/core": "^31.72.0",
         "@date-vir/duration": "^8.3.2",
         "@paralleldrive/cuid2": "^3.3.0",
         "ansi-styles": "^6.2.3",