randomcryp 1.0.5 → 2.0.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 ~3KB 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.
 
@@ -40,22 +40,23 @@ 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(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` |
+| **`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. | `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.
 License: BSD-3-Clause.

package/dist/index.d.ts

@@ -1,129 +1,34 @@
-declare module "lib/uSafeInt" {
-    /**
-     * Generates a random integer
-     * between 0 (inclusive) and {@link Number.MAX_SAFE_INTEGER} (inclusive)
-     * with 53 bits precission.
-     **/
-    export const uSafeInt: () => number;
-}
-declare module "lib/bool" {
-    /**
-     * Generates a boolean value randomly.
-     * true and false are equally likely.
-     **/
-    export const bool: () => boolean;
-}
-declare module "lib/boolean" {
-    export { bool as boolean } from "lib/bool";
-}
-declare module "lib/float" {
-    /**
-     * Generates a random number between 0 (inclusive) and 1 (exclusive).
-     * with 53 bits precission.
-     **/
-    export const float: () => number;
-}
-declare module "lib/choice" {
-    /**
-     * Randomly choose an element from an array-like object.
-     * @returns undefined if the array is empty.
-     * @returns a random element from the array if at least one element is present.
-     * @example choice([1, 2, 3]) // 2
-     */
-    export const choice: <E>(choices: ArrayLike<E>) => E | undefined;
-}
-declare module "lib/safeInt" {
-    /**
-     * Generates a random integer
-     * between {@link Number.MIN_SAFE_INTEGER} (inclusive) and {@link Number.MAX_SAFE_INTEGER} (inclusive).
-     * +0 and -0 can both appear, and technically 54 bit in precision but not recommended for general usage.
-     *
-     * Use {@link uSafeInt} for instead.
-     **/
-    export const safeInt: () => number;
-}
-declare module "lib/ifloat" {
-    /**
-     * Generates a random number between -1 (inclusive) and 1 (inclusive).
-     * Uses {@link safeInt} and thus not recommended for general usage also.
-     *
-     * Should be somewhat better for calculating PI.
-     **/
-    export const ifloat: () => number;
-}
-declare module "lib/percentage" {
-    /**
-     * 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.
-     **/
-    export const percentage: (input: number) => boolean;
-}
-declare module "lib/pick" {
-    export { choice as pick } from "lib/choice";
-}
-declare module "lib/rangeInt" {
-    /**
-     * Generates a random number integer
-     * between given `min` (inclusive) and `max` (inclusive).
-     * Throws if `min` > `max`.
-     *
-     * @example rangeInt(1, 100) // 35
-     */
-    export const rangeInt: (min: number, max: number) => number;
-}
-declare module "lib/randInt" {
-    export { rangeInt as randInt } from "lib/rangeInt";
-}
-declare module "lib/random" {
-    export { float as random } from "lib/float";
-}
-declare module "lib/range" {
-    /**
-     * Generates a random number (not integer)
-     * between given `min` (inclusive) and `max` (exclusive).
-     * Throws if `min` > `max`.
-     *
-     * @example range(1, 10) // 2.4802525465053487
-     */
-    export const range: (min: number, max: number) => number;
-}
-declare module "lib/shuffle" {
-    /**
-     * Randomly shuffles the elements of an array ***in place***. The original array is modified.
-     */
-    export const shuffle: <E>(array: Array<E>) => Array<E>;
-}
-declare module "index" {
-    import { bool } from "lib/bool";
-    import { boolean } from "lib/boolean";
-    import { choice } from "lib/choice";
-    import { float } from "lib/float";
-    import { ifloat } from "lib/ifloat";
-    import { percentage } from "lib/percentage";
-    import { pick } from "lib/pick";
-    import { randInt } from "lib/randInt";
-    import { random } from "lib/random";
-    import { range } from "lib/range";
-    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, };
-    const _default: {
-        bool: () => boolean;
-        boolean: () => boolean;
-        choice: <E>(choices: ArrayLike<E>) => E | undefined;
-        float: () => number;
-        ifloat: () => number;
-        percentage: (input: 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>;
-        uSafeInt: () => number;
-    };
-    export default _default;
-}
+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 { randInt } from "./lib/randInt";
+import { random } from "./lib/random";
+import { range } from "./lib/range";
+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, hex, ifloat, percentage, pick, 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;
+    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: 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);
@@ -55,15 +72,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,6 +89,7 @@ var src_default = {
   boolean: bool,
   choice,
   float,
+  hex,
   ifloat,
   percentage,
   pick: choice,
@@ -93,6 +112,7 @@ export {
   choice as pick,
   percentage,
   ifloat,
+  hex,
   float,
   src_default as default,
   choice,

package/dist/lib/bool.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates a boolean value randomly.
+ * true and false are equally likely.
+ **/
+export declare const bool: () => boolean;

package/dist/lib/boolean.d.ts

@@ -0,0 +1 @@
+export { bool as boolean } from "./bool";

package/dist/lib/choice.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Randomly choose an element from an array-like object.
+ * @returns undefined if the array is empty.
+ * @returns a random element from the array if at least one element is present.
+ * @example choice([1, 2, 3]) // 2
+ */
+export declare const choice: <E>(choices: ArrayLike<E>) => E | undefined;

package/dist/lib/float.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates a random number between 0 (inclusive) and 1 (exclusive).
+ * with 53 bits precission.
+ **/
+export declare const float: () => number;

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/ifloat.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generates a random number between -1 (inclusive) and 1 (inclusive).
+ * Uses {@link safeInt} and thus not recommended for general usage also.
+ *
+ * Should be somewhat better for calculating PI.
+ **/
+export declare const ifloat: () => number;

package/dist/lib/percentage.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 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.
+ **/
+export declare const percentage: (input: number) => boolean;

package/dist/lib/pick.d.ts

@@ -0,0 +1 @@
+export { choice as pick } from "./choice";

package/dist/lib/randInt.d.ts

@@ -0,0 +1 @@
+export { rangeInt as randInt } from "./rangeInt";

package/dist/lib/random.d.ts

@@ -0,0 +1 @@
+export { float as random } from "./float";

package/dist/lib/range.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Generates a random number (not integer)
+ * between given `min` (inclusive) and `max` (exclusive).
+ * Throws if `min` > `max`.
+ *
+ * @example range(1, 10) // 2.4802525465053487
+ */
+export declare const range: (min: number, max: number) => number;

package/dist/lib/rangeInt.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Generates a random number integer
+ * between given `min` (inclusive) and `max` (inclusive).
+ * Throws if `min` > `max`.
+ *
+ * @example rangeInt(1, 100) // 35
+ */
+export declare const rangeInt: (min: number, max: number) => number;

package/dist/lib/safeInt.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Generates a random integer
+ * between {@link Number.MIN_SAFE_INTEGER} (inclusive) and {@link Number.MAX_SAFE_INTEGER} (inclusive).
+ * +0 and -0 can both appear, and technically 54 bit in precision but not recommended for general usage.
+ *
+ * Use {@link uSafeInt} for instead.
+ **/
+export declare const safeInt: () => number;

package/dist/lib/shuffle.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns a new string containing the characters of the input string in a shuffled order.
+ */
+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/dist/lib/uSafeInt.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generates a random integer
+ * between 0 (inclusive) and {@link Number.MAX_SAFE_INTEGER} (inclusive)
+ * with 53 bits precission.
+ **/
+export declare const uSafeInt: () => number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "randomcryp",
-  "version": "1.0.5",
+  "version": "2.0.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,7 +20,7 @@
     "build": "bun build src/index.ts --outdir dist && tsc -p tsconfig.dts.json"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.5",
+    "@types/bun": "^1.2.8",
     "prettier": "^3.5.3",
     "typescript": "^5.8.2"
   },