@augment-vir/common 19.5.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/object/nested-keys.js

@@ -1,7 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getValueFromNestedKeys = void 0;
+exports.getValueFromNestedKeys = exports.setValueWithNestedKeys = void 0;
+const object_1 = require("./object");
 const typed_has_property_1 = require("./typed-has-property");
+function setValueWithNestedKeys(inputObject, nestedKeys, value) {
+    /**
+     * Lots of as any casts in here because these types are, under the hood, pretty complex. Since
+     * the inputs and outputs of this function are well typed, these internal as any casts do not
+     * affect the external API of this function.
+     */
+    const nextKey = nestedKeys[0];
+    if (!(nextKey in inputObject)) {
+        inputObject[nextKey] = {};
+    }
+    else if (!(0, object_1.isObject)(inputObject[nextKey])) {
+        throw new Error(`Cannot set value at key '${String(nextKey)}' as its not an object.`);
+    }
+    const nextParent = inputObject[nextKey];
+    if (nestedKeys.length > 2) {
+        setValueWithNestedKeys(nextParent, nestedKeys.slice(1), value);
+    }
+    else {
+        nextParent[nestedKeys[1]] = value;
+    }
+}
+exports.setValueWithNestedKeys = setValueWithNestedKeys;
 function getValueFromNestedKeys(inputObject, nestedKeys) {
     /**
      * Lots of as any casts in here because these types are, under the hood, pretty complex. Since

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/object/nested-keys.js

@@ -1,4 +1,26 @@
+import { isObject } from './object';
 import { typedHasProperty } from './typed-has-property';
+export function setValueWithNestedKeys(inputObject, nestedKeys, value) {
+    /**
+     * Lots of as any casts in here because these types are, under the hood, pretty complex. Since
+     * the inputs and outputs of this function are well typed, these internal as any casts do not
+     * affect the external API of this function.
+     */
+    const nextKey = nestedKeys[0];
+    if (!(nextKey in inputObject)) {
+        inputObject[nextKey] = {};
+    }
+    else if (!isObject(inputObject[nextKey])) {
+        throw new Error(`Cannot set value at key '${String(nextKey)}' as its not an object.`);
+    }
+    const nextParent = inputObject[nextKey];
+    if (nestedKeys.length > 2) {
+        setValueWithNestedKeys(nextParent, nestedKeys.slice(1), value);
+    }
+    else {
+        nextParent[nestedKeys[1]] = value;
+    }
+}
 export function getValueFromNestedKeys(inputObject, nestedKeys) {
     /**
      * Lots of as any casts in here because these types are, under the hood, pretty complex. Since

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/object/nested-keys.d.ts

@@ -8,4 +8,5 @@ export type NestedKeys<ObjectGeneric extends object> = UnionToIntersection<Extra
     ...(NestedKeys<UnionToIntersection<Extract<PropertyValueType<ObjectGeneric>, object>>> | [])
 ] : [keyof ObjectGeneric];
 export type NestedValue<ObjectGeneric extends object, NestedKeysGeneric extends NestedSequentialKeys<ObjectGeneric>> = NestedKeysGeneric extends readonly [infer FirstEntry, ...infer FollowingEntries] ? FirstEntry extends keyof ObjectGeneric ? FollowingEntries extends never[] ? ObjectGeneric[FirstEntry] : ObjectGeneric[FirstEntry] extends object ? FollowingEntries extends NestedSequentialKeys<ObjectGeneric[FirstEntry]> ? NestedValue<ObjectGeneric[FirstEntry], FollowingEntries> : never : never : never : never;
+export declare function setValueWithNestedKeys<const ObjectGeneric extends object, const KeysGeneric extends NestedSequentialKeys<ObjectGeneric>>(inputObject: ObjectGeneric, nestedKeys: KeysGeneric, value: NestedValue<ObjectGeneric, KeysGeneric>): void;
 export declare function getValueFromNestedKeys<const ObjectGeneric extends object, const KeysGeneric extends NestedSequentialKeys<ObjectGeneric>>(inputObject: ObjectGeneric, nestedKeys: KeysGeneric): NestedValue<ObjectGeneric, KeysGeneric> | undefined;

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.5.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": {