randomcryp 1.0.6 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # randomcryp
 
-A cryptographically secure, feature rich, zero dependency, lightweight and browser friendly random number generator library. Only ~4KB in size.
+A cryptographically secure, feature rich, zero dependency, lightweight and browser friendly random number generator library. Only ~5KB in size.
 Uses [Crypto.getRandomValues()](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) to get its randomness.
 The spelling is random-creep in case you are wondering.
 
@@ -9,7 +9,7 @@ The spelling is random-creep in case you are wondering.
 - Lightweight
 - Browser friendly
 - TypeScript definitions
-- Lots of methods and commonn aliases
+- Lots of methods and common aliases
 - Batteries Included (Zero dependencies)
 - Supported in all major JavaScript / TypeScript runtimes (Browser, Node, Deno, Bun etc.)
 
@@ -40,22 +40,24 @@ rangeInt(1, 10); // 7
 
 #### List of Methods
 
-| Method                                           | Description                                                                                                                                                                                               | Aliases                                          |
-| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| **`bool(): boolean`**                            | Generates a random boolean (`true` or `false`).                                                                                                                                                           | `bool()` → `true`                                |
-| **`boolean(): boolean`**                         | Alias for `bool()`.                                                                                                                                                                                       | `boolean()` → `false`                            |
-| **`percentage(val: number): boolean`**           | Generates `true` at given percentage of time.                                                                                                                                                             | `percentage(20)` → `false`                       |
-| **`uSafeInt(): number`**                         | Generates a random integer between `0` (inclusive) and `Number.MAX_SAFE_INTEGER` (inclusive).                                                                                                             | `uSafeInt()` → `4946544243668033`                |
-| **`float(): number`**                            | Generates a random number between `0` (inclusive) and `1` (exclusive).                                                                                                                                    | `number()` → `0.190088246732104`                 |
-| **`random(): number`**                           | Alias for `float()`.                                                                                                                                                                                      | `random()` → `0.9520779718919631`                |
-| **`choice(arr: ArrayLike<E>): E`**               | Selects a random element from an array.                                                                                                                                                                   | `choice([1, 2, 3, 4, 5])` → `3`                  |
-| **`pick(arr: ArrayLike<E>): E`**                 | Alias for `choice()`.                                                                                                                                                                                     | `pick([1, 2, 3, 4, 5])` → `1`                    |
-| **`shuffle(arr: Array<E>): E`**                  | Shuffles the elements of an array randomly in-place and returns a reference to the original array.                                                                                                        | `shuffle([1, 2, 3, 4, 5])` → `[ 1, 3, 2, 5, 4 ]` |
-| **`range(min: number, max: number): number`**    | Generates a random number (not integer) between given `min` (inclusive) and `max` (exclusive). Throws if `min` > `max`.                                                                                   | `range(1, 5)` → `4.103370176158448`              |
-| **`rangeInt(min: number, max: number): number`** | Generates a random number (not integer) between given `min` (inclusive) and `max` (exclusive). Throws if `min` > `max`.                                                                                   | `rangeInt(1, 10)` → `8`                          |
-| **`randInt(min: number, max: number): number`**  | Alias for `rangeInt()`.                                                                                                                                                                                   | `randInt(1, 100)` → `35`                         |
-| **`safeInt(): number`**                          | Generates a random integer between `Number.MIN_SAFE_INTEGER` (inclusive) and `Number.MAX_SAFE_INTEGER` (inclusive). +0 and -0 both can be generated. 54 bits precision. Not recommended for genral usage. | `safeInt()` → `-5802548511349229`                |
-| **`ifloat(): number`**                           | Generates a random number between `-1` (inclusive) and `1` (inclusive). Uses `safeInt()` and thus not recommended.                                                                                        | `ifloat()` → `-0.6076475248861822`               |
-
-© 2025, Md. Touhidur Rahman
+| Method | Description | Aliases |
+| -- | -- | -- |
+| **`bool(): boolean`** | Generates a random boolean (`true` or `false`). | `bool()` → `true` |
+| **`boolean(): boolean`** | Alias for `bool()`. | `boolean()` → `false` |
+| **`percentage(p: number): boolean`** | Generates `true` at given percentage of time. | `percentage(20)` → `false` |
+| **`probability(p: number): boolean`** | Generates `true` with a given probability `p` and `false` with probability `1-p`. | `probability(0.8)` → `true` |
+| **`uSafeInt(): number`** | Generates a random integer between `0` (inclusive) and `Number.MAX_SAFE_INTEGER` (inclusive). | `uSafeInt()` → `4946544243668033` |
+| **`float(): number`** | Generates a random number between `0` (inclusive) and `1` (exclusive). | `number()` → `0.190088246732104` |
+| **`random(): number`** | Alias for `float()`. | `random()` → `0.9520779718919631` |
+| **`hex(length: number = 8, prefix: boolean = false): string`** | Generates a random hex string of the specified length (default 8). Optionally prefixes with '0x'. | `hex(16)` → `d1ef0149c7849844` |
+| **`choice(arr: ArrayLike<E>): E`** | Selects a random element from an array. | `choice([1, 2, 3, 4, 5])` → `3` |
+| **`pick(arr: ArrayLike<E>): E`** | Alias for `choice()`. | `pick([1, 2, 3, 4, 5])` → `1` |
+| **`shuffle(input: string): string`**, **`shuffle(input: Array<E>): Array<E>`** | Returns a new array or string after shuffling the given array or string randomly. | `shuffle([1, 2, 3, 4, 5])` → `[ 1, 3, 2, 5, 4 ]` |
+| **`range(min: number, max: number): number`** | Generates a random number (not integer) between given `min` (inclusive) and `max` (exclusive). Throws if `min` > `max`. | `range(1, 5)` → `4.103370176158448` |
+| **`rangeInt(min: number, max: number): number`** | Generates a random number (not integer) between given `min` (inclusive) and `max` (exclusive). Throws if `min` > `max`. | `rangeInt(1, 10)` → `8` |
+| **`randInt(min: number, max: number): number`** | Alias for `rangeInt()`. | `randInt(1, 100)` → `35` |
+| **`safeInt(): number`** | Generates a random integer between `Number.MIN_SAFE_INTEGER` (inclusive) and `Number.MAX_SAFE_INTEGER` (inclusive). +0 and -0 both can be generated. 54 bits precision. Not recommended for general usage. | `safeInt()` → `-5802548511349229` |
+| **`ifloat(): number`** | Generates a random number between `-1` (inclusive) and `1` (inclusive). Uses `safeInt()` and thus not recommended. | `ifloat()` → `-0.6076475248861822` |
+
+© 2025, Md. Touhidur Rahman.
 License: BSD-3-Clause.

package/dist/index.d.ts

@@ -2,9 +2,11 @@ import { bool } from "./lib/bool";
 import { boolean } from "./lib/boolean";
 import { choice } from "./lib/choice";
 import { float } from "./lib/float";
+import { hex } from "./lib/hex";
 import { ifloat } from "./lib/ifloat";
 import { percentage } from "./lib/percentage";
 import { pick } from "./lib/pick";
+import { probability } from "./lib/probability";
 import { randInt } from "./lib/randInt";
 import { random } from "./lib/random";
 import { range } from "./lib/range";
@@ -12,21 +14,23 @@ import { rangeInt } from "./lib/rangeInt";
 import { safeInt } from "./lib/safeInt";
 import { shuffle } from "./lib/shuffle";
 import { uSafeInt } from "./lib/uSafeInt";
-export { bool, boolean, choice, float, ifloat, percentage, pick, randInt, random, range, rangeInt, safeInt, shuffle, uSafeInt, };
+export { bool, boolean, choice, float, hex, ifloat, percentage, pick, probability, randInt, random, range, rangeInt, safeInt, shuffle, uSafeInt, };
 declare const _default: {
     bool: () => boolean;
     boolean: () => boolean;
     choice: <E>(choices: ArrayLike<E>) => E | undefined;
     float: () => number;
+    hex: (length?: number, prefix?: boolean) => string;
     ifloat: () => number;
-    percentage: (input: number) => boolean;
+    percentage: (p: number) => boolean;
+    probability: (p: number) => boolean;
     pick: <E>(choices: ArrayLike<E>) => E | undefined;
     randInt: (min: number, max: number) => number;
     random: () => number;
     range: (min: number, max: number) => number;
     rangeInt: (min: number, max: number) => number;
     safeInt: () => number;
-    shuffle: <E>(array: Array<E>) => Array<E>;
+    shuffle: typeof shuffle;
     uSafeInt: () => number;
 };
 export default _default;

package/dist/index.js

@@ -20,6 +20,23 @@ var choice = (choices) => {
   return choices[Math.floor(float() * choices.length)];
 };
 
+// src/lib/hex.ts
+var digits = "0123456789abcdef";
+var hex = (length = 8, prefix = false) => {
+  const randArr = crypto.getRandomValues(new Uint8Array(Math.ceil(length / 2)));
+  const hexArr = new Array(randArr.length);
+  for (let i = 0, j = 0;i < length; i++, j = Math.floor(i / 2)) {
+    if (i % 2 === 0) {
+      hexArr[i] = digits[randArr[j] >> 4];
+    } else {
+      hexArr[i] = digits[randArr[j] & 15];
+    }
+  }
+  if (prefix)
+    return "0x" + hexArr.join("");
+  return hexArr.join("");
+};
+
 // src/lib/safeInt.ts
 var POW_2_372 = Math.pow(2, 37);
 var POW_2_212 = Math.pow(2, 21);
@@ -33,12 +50,20 @@ var safeInt = () => {
 var ifloat = () => safeInt() / Number.MAX_SAFE_INTEGER;
 
 // src/lib/percentage.ts
-var percentage = (input) => {
-  if (input < 0 || input > 100) {
-    throw new RangeError("input value should be between 0 and 100");
+var percentage = (p) => {
+  if (p < 0 || p > 100) {
+    throw new RangeError(`${p} is not in range [0, 100]`);
   }
-  return float() * 100 < input;
+  return float() * 100 < p;
 };
+// src/lib/probability.ts
+var probability = (p) => {
+  if (p < 0 || p > 1) {
+    throw new RangeError(`${p} is not in range [0, 1]`);
+  }
+  return float() < p;
+};
+
 // src/lib/rangeInt.ts
 var rangeInt = (min, max) => {
   if (min > max) {
@@ -55,15 +80,16 @@ var range = (min, max) => {
 };
 
 // src/lib/shuffle.ts
-var shuffle = (array) => {
+function shuffle(input) {
+  const array = Array.from(input);
   for (let i = array.length - 1;i > 0; i--) {
     const pick = Math.floor(float() * (i + 1));
     const temp = array[i];
     array[i] = array[pick];
     array[pick] = temp;
   }
-  return array;
-};
+  return typeof input === "string" ? array.join("") : array;
+}
 
 // src/index.ts
 var src_default = {
@@ -71,8 +97,10 @@ var src_default = {
   boolean: bool,
   choice,
   float,
+  hex,
   ifloat,
   percentage,
+  probability,
   pick: choice,
   randInt: rangeInt,
   random: float,
@@ -90,9 +118,11 @@ export {
   range,
   float as random,
   rangeInt as randInt,
+  probability,
   choice as pick,
   percentage,
   ifloat,
+  hex,
   float,
   src_default as default,
   choice,

package/dist/lib/hex.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generates a random hex string of the specified length.
+ * @param {number} [length=8] - The length of the hex string to generate. Default is `8`.
+ * @param {boolean} [prefix=false] - If true, the hex string will be prefixed with "0x". Default `false`.
+ * @returns {string} A random hex string of the specified length.
+ */
+export declare const hex: (length?: number, prefix?: boolean) => string;

package/dist/lib/percentage.d.ts

@@ -1,5 +1,6 @@
 /**
- * Generates true with the probability of the percentage value given.
+ * Generates `true` with the probability of the percentage value given.
  * @example percentage(20) // should return true 20% of the time and false 80% of the time.
+ * @throws RangeError if `p` is not range `[0, 100]`.
  **/
-export declare const percentage: (input: number) => boolean;
+export declare const percentage: (p: number) => boolean;

package/dist/lib/probability.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generates `true` with a given probability `p` and `false` with probability `1-p`.
+ * @throws {RangeError} If `p` is not in range `[0, 1]`.
+ * @example probability(0.8); // returns true 80% of the time and false 20% of the time.
+ */
+export declare const probability: (p: number) => boolean;

package/dist/lib/shuffle.d.ts

@@ -1,4 +1,9 @@
 /**
- * Randomly shuffles the elements of an array ***in place***. The original array is modified.
+ * Returns a new string containing the characters of the input string in a shuffled order.
  */
-export declare const shuffle: <E>(array: Array<E>) => Array<E>;
+declare function shuffle(input: string): string;
+/**
+ * Returns a new array containing the elements of the input array in a shuffled order.
+ */
+declare function shuffle<E>(input: E[]): E[];
+export { shuffle };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "randomcryp",
-  "version": "1.0.6",
+  "version": "2.1.0",
   "license": "BSD-3-Clause",
   "description": "A cryptographically secure, feature rich, zero dependency and browser friendly random number generator library.",
   "author": {
@@ -11,6 +11,7 @@
   "homepage": "https://github.com/touhidurrr/randomcryp",
   "bugs": "https://github.com/touhidurrr/randomcryp/issues",
   "funding": "https://buymeacoffee.com/touhidurrr",
+  "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,9 +20,9 @@
     "build": "bun build src/index.ts --outdir dist && tsc -p tsconfig.dts.json"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.5",
+    "@types/bun": "^1.2.9",
     "prettier": "^3.5.3",
-    "typescript": "^5.8.2"
+    "typescript": "^5.8.3"
   },
   "keywords": [
     "cryptographically-secure",