@augment-vir/common 19.6.0 → 20.0.0

package/README.md

@@ -3,3 +3,5 @@
 `augment-vir` is a collection of small helper functions that I constantly use across all my JavaScript and TypeScript repos. I call these functions `augments`. These are functions, constants, and types typically placed within a "util", or "helpers", etc. directory.
 
 This `common` package is for environment-agnostic augments. Everything in here will work in Node.js or the browser with identical results.
+
+Note that the `random*` functions exported by this package will not work in Node.js < v19.0.0.

package/dist/cjs/augments/random.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.randomString = exports.createUuid = exports.randomBoolean = exports.randomInteger = void 0;
+const common_number_1 = require("./common-number");
+const crypto = globalThis.crypto;
+// can't get this coverage to work
+/* c8 ignore start */
+/**
+ * Creates a random integer (decimal points are all cut off) between the given min and max
+ * (inclusive).
+ *
+ * This function uses cryptographically secure randomness.
+ */
+function randomInteger({ min: rawMin, max: rawMax }) {
+    const { min, max } = (0, common_number_1.ensureMinAndMax)({ min: Math.floor(rawMin), max: Math.floor(rawMax) });
+    const range = max - min + 1;
+    const neededByteCount = Math.ceil(Math.log2(range) / 8);
+    const cutoff = Math.floor(256 ** neededByteCount / range) * range;
+    const currentBytes = new Uint8Array(neededByteCount);
+    let value;
+    do {
+        crypto.getRandomValues(currentBytes);
+        value = currentBytes.reduce((accum, byte, index) => {
+            return accum + byte * 256 ** index;
+        }, 0);
+    } while (value >= cutoff);
+    return min + (value % range);
+}
+exports.randomInteger = randomInteger;
+/**
+ * Returns true at rate of the percentLikelyToBeTrue input. Inputs should be whole numbers which
+ * will be treated like percents. Anything outside of 0-100 inclusively will be clamped. An input 0
+ * will always return true. An input of 100 will always return true. Decimals on the input will be
+ * chopped off, use whole numbers.
+ *
+ * This function uses cryptographically secure randomness.
+ *
+ * @example
+ *     randomBoolean(50); // 50% chance to return true
+ *
+ * @example
+ *     randomBoolean(0); // always false, 0% chance of being true
+ *
+ * @example
+ *     randomBoolean(100); // always true, 100% chance of being true
+ *
+ * @example
+ *     randomBoolean(59.67; // 59% chance of being true
+ */
+function randomBoolean(percentLikelyToBeTrue = 50) {
+    return (randomInteger({ min: 0, max: 99 }) <
+        (0, common_number_1.clamp)({
+            value: Math.floor(percentLikelyToBeTrue),
+            min: 0,
+            max: 100,
+        }));
+}
+exports.randomBoolean = randomBoolean;
+/** Creates a cryptographically secure uuid. */
+function createUuid() {
+    return crypto.randomUUID();
+}
+exports.createUuid = createUuid;
+/**
+ * Creates a random string (including letters and numbers) of a given length.
+ *
+ * This function uses cryptographically secure randomness.
+ */
+function randomString(inputLength = 16) {
+    const arrayLength = Math.ceil(inputLength / 2);
+    const uintArray = new Uint8Array(arrayLength);
+    crypto.getRandomValues(uintArray);
+    return (Array.from(uintArray)
+        .map((value) => value.toString(16).padStart(2, '0'))
+        .join('')
+        /**
+         * Because getRandomValues works with even numbers only, we must then chop off extra
+         * characters if they exist in the even that inputLength was odd.
+         */
+        .substring(0, inputLength));
+}
+exports.randomString = randomString;
+/* c8 ignore stop */

package/dist/cjs/index.js

@@ -41,6 +41,7 @@ __exportStar(require("./augments/object/old-union-to-intersection"), exports);
 __exportStar(require("./augments/object/pick-deep"), exports);
 __exportStar(require("./augments/object/typed-has-property"), exports);
 __exportStar(require("./augments/promise"), exports);
+__exportStar(require("./augments/random"), exports);
 __exportStar(require("./augments/regexp"), exports);
 __exportStar(require("./augments/runtime-type-of"), exports);
 __exportStar(require("./augments/string/prefixes"), exports);

package/dist/esm/augments/random.js

@@ -0,0 +1,76 @@
+import { clamp, ensureMinAndMax } from './common-number';
+const crypto = globalThis.crypto;
+// can't get this coverage to work
+/* c8 ignore start */
+/**
+ * Creates a random integer (decimal points are all cut off) between the given min and max
+ * (inclusive).
+ *
+ * This function uses cryptographically secure randomness.
+ */
+export function randomInteger({ min: rawMin, max: rawMax }) {
+    const { min, max } = ensureMinAndMax({ min: Math.floor(rawMin), max: Math.floor(rawMax) });
+    const range = max - min + 1;
+    const neededByteCount = Math.ceil(Math.log2(range) / 8);
+    const cutoff = Math.floor(256 ** neededByteCount / range) * range;
+    const currentBytes = new Uint8Array(neededByteCount);
+    let value;
+    do {
+        crypto.getRandomValues(currentBytes);
+        value = currentBytes.reduce((accum, byte, index) => {
+            return accum + byte * 256 ** index;
+        }, 0);
+    } while (value >= cutoff);
+    return min + (value % range);
+}
+/**
+ * Returns true at rate of the percentLikelyToBeTrue input. Inputs should be whole numbers which
+ * will be treated like percents. Anything outside of 0-100 inclusively will be clamped. An input 0
+ * will always return true. An input of 100 will always return true. Decimals on the input will be
+ * chopped off, use whole numbers.
+ *
+ * This function uses cryptographically secure randomness.
+ *
+ * @example
+ *     randomBoolean(50); // 50% chance to return true
+ *
+ * @example
+ *     randomBoolean(0); // always false, 0% chance of being true
+ *
+ * @example
+ *     randomBoolean(100); // always true, 100% chance of being true
+ *
+ * @example
+ *     randomBoolean(59.67; // 59% chance of being true
+ */
+export function randomBoolean(percentLikelyToBeTrue = 50) {
+    return (randomInteger({ min: 0, max: 99 }) <
+        clamp({
+            value: Math.floor(percentLikelyToBeTrue),
+            min: 0,
+            max: 100,
+        }));
+}
+/** Creates a cryptographically secure uuid. */
+export function createUuid() {
+    return crypto.randomUUID();
+}
+/**
+ * Creates a random string (including letters and numbers) of a given length.
+ *
+ * This function uses cryptographically secure randomness.
+ */
+export function randomString(inputLength = 16) {
+    const arrayLength = Math.ceil(inputLength / 2);
+    const uintArray = new Uint8Array(arrayLength);
+    crypto.getRandomValues(uintArray);
+    return (Array.from(uintArray)
+        .map((value) => value.toString(16).padStart(2, '0'))
+        .join('')
+        /**
+         * Because getRandomValues works with even numbers only, we must then chop off extra
+         * characters if they exist in the even that inputLength was odd.
+         */
+        .substring(0, inputLength));
+}
+/* c8 ignore stop */

package/dist/esm/index.js

@@ -25,6 +25,7 @@ export * from './augments/object/old-union-to-intersection';
 export * from './augments/object/pick-deep';
 export * from './augments/object/typed-has-property';
 export * from './augments/promise';
+export * from './augments/random';
 export * from './augments/regexp';
 export * from './augments/runtime-type-of';
 export * from './augments/string/prefixes';

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

@@ -0,0 +1,39 @@
+/**
+ * Creates a random integer (decimal points are all cut off) between the given min and max
+ * (inclusive).
+ *
+ * This function uses cryptographically secure randomness.
+ */
+export declare function randomInteger({ min: rawMin, max: rawMax }: {
+    min: number;
+    max: number;
+}): number;
+/**
+ * Returns true at rate of the percentLikelyToBeTrue input. Inputs should be whole numbers which
+ * will be treated like percents. Anything outside of 0-100 inclusively will be clamped. An input 0
+ * will always return true. An input of 100 will always return true. Decimals on the input will be
+ * chopped off, use whole numbers.
+ *
+ * This function uses cryptographically secure randomness.
+ *
+ * @example
+ *     randomBoolean(50); // 50% chance to return true
+ *
+ * @example
+ *     randomBoolean(0); // always false, 0% chance of being true
+ *
+ * @example
+ *     randomBoolean(100); // always true, 100% chance of being true
+ *
+ * @example
+ *     randomBoolean(59.67; // 59% chance of being true
+ */
+export declare function randomBoolean(percentLikelyToBeTrue?: number): boolean;
+/** Creates a cryptographically secure uuid. */
+export declare function createUuid(): `${string}-${string}-${string}-${string}-${string}`;
+/**
+ * Creates a random string (including letters and numbers) of a given length.
+ *
+ * This function uses cryptographically secure randomness.
+ */
+export declare function randomString(inputLength?: number): string;

package/dist/types/index.d.ts

@@ -25,6 +25,7 @@ export * from './augments/object/old-union-to-intersection';
 export * from './augments/object/pick-deep';
 export * from './augments/object/typed-has-property';
 export * from './augments/promise';
+export * from './augments/random';
 export * from './augments/regexp';
 export * from './augments/runtime-type-of';
 export * from './augments/string/prefixes';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/common",
-    "version": "19.6.0",
+    "version": "20.0.0",
     "homepage": "https://github.com/electrovir/augment-vir/tree/main/packages/common",
     "bugs": {
         "url": "https://github.com/electrovir/augment-vir/issues"
@@ -24,6 +24,7 @@
         "test:types": "tsc --noEmit"
     },
     "dependencies": {
+        "browser-or-node": "^2.1.1",
         "type-fest": "^4.4.0"
     },
     "devDependencies": {