randomcryp 1.0.4

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Md. Touhidur Rahman
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,60 @@
+# randomcryp
+
+A cryptographically secure, feature rich, zero dependency, lightweight and browser friendly random number generator library. Only ~3KB 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.
+
+## Featues
+
+- Lightweight
+- Browser friendly
+- TypeScript definitions
+- Lots of methods and commonn aliases
+- Batteries Included (Zero dependencies)
+- Supported in all major JavaScript / TypeScript runtimes (Browser, Node, Deno, Bun etc.)
+
+## Install
+
+```bash
+bun add randomcryp # bun
+yarn add randomcryp # yarn
+pnpm add randomcryp # pnpm
+npm install randomcryp # npm
+```
+
+## Usage
+
+```ts
+import random from "randomcryp";
+
+float(); // 0.190088246732104
+```
+
+Or,
+
+```ts
+import { rangeInt } from "randomcryp";
+
+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`               |
+
+License, BSD-3-Clause

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+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;
+}

package/dist/index.js

@@ -0,0 +1,101 @@
+// src/lib/uSafeInt.ts
+var POW_2_37 = Math.pow(2, 37);
+var POW_2_21 = Math.pow(2, 21);
+var POW_2_5 = Math.pow(2, 5);
+var uSafeInt = () => {
+  const [num1, num2, num3, num4] = crypto.getRandomValues(new Uint16Array(4));
+  return num1 * POW_2_37 + num2 * POW_2_21 + num3 * POW_2_5 + (num4 & POW_2_5 - 1);
+};
+
+// src/lib/bool.ts
+var bool = () => uSafeInt() % 2 === 0;
+// src/lib/float.ts
+var POW_2_53 = Math.pow(2, 53);
+var float = () => uSafeInt() / POW_2_53;
+
+// src/lib/choice.ts
+var choice = (choices) => {
+  if (choices.length === 0)
+    return;
+  return choices[Math.floor(float() * choices.length)];
+};
+
+// src/lib/safeInt.ts
+var POW_2_372 = Math.pow(2, 37);
+var POW_2_212 = Math.pow(2, 21);
+var POW_2_52 = Math.pow(2, 5);
+var safeInt = () => {
+  const [num1, num2, num3, num4] = crypto.getRandomValues(new Uint16Array(4));
+  return ((num4 & POW_2_52) < 1 ? 1 : -1) * (num1 * POW_2_372 + num2 * POW_2_212 + num3 * POW_2_52 + (num4 & POW_2_52 - 1));
+};
+
+// src/lib/ifloat.ts
+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");
+  }
+  return float() * 100 < input;
+};
+// src/lib/rangeInt.ts
+var rangeInt = (min, max) => {
+  if (min > max) {
+    throw new RangeError("min must be less than or equal to max");
+  }
+  return min + Math.floor(float() * (max - min + 1));
+};
+// src/lib/range.ts
+var range = (min, max) => {
+  if (min > max) {
+    throw new RangeError("min must be less than or equal to max");
+  }
+  return min + float() * (max - min);
+};
+
+// src/lib/shuffle.ts
+var shuffle = (array) => {
+  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;
+};
+
+// src/index.ts
+var src_default = {
+  bool,
+  boolean: bool,
+  choice,
+  float,
+  ifloat,
+  percentage,
+  pick: choice,
+  randInt: rangeInt,
+  random: float,
+  range,
+  rangeInt,
+  safeInt,
+  shuffle,
+  uSafeInt
+};
+export {
+  uSafeInt,
+  shuffle,
+  safeInt,
+  rangeInt,
+  range,
+  float as random,
+  rangeInt as randInt,
+  choice as pick,
+  percentage,
+  ifloat,
+  float,
+  src_default as default,
+  choice,
+  bool as boolean,
+  bool
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "randomcryp",
+  "version": "1.0.4",
+  "license": "BSD-3-Clause",
+  "description": "A cryptographically secure, feature rich, zero dependency and browser friendly random number generator library.",
+  "author": {
+    "name": "Md. Touhidur Rahman",
+    "email": "touhidurrr@pm.me"
+  },
+  "repository": "github:touhidurrr/randomcryp",
+  "homepage": "https://github.com/touhidurrr/randomcryp",
+  "bugs": "https://github.com/touhidurrr/randomcryp/issues",
+  "funding": "https://buymeacoffee.com/touhidurrr",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "format": "prettier --write .",
+    "build": "bun build src/index.ts --outdir dist && tsc -p tsconfig.dts.json"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.5",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.2"
+  }
+}