@shreykc/true-random

A lightweight Node.js module for generating enhanced random integers using a combination of:

• 🔐 crypto.randomBytes() (cryptographic entropy)
• ⏱ Date.now() (time-based entropy)

This adds an additional unpredictability layer beyond standard crypto usage.

📦 Installation

npm install @shreykc/true-random

🚀 Usage

const { generateTrueRandom } = require("@shreykc/true-random");

// Default range (0 - 100)
console.log(generateTrueRandom());

// Custom range
console.log(generateTrueRandom(1, 10));
console.log(generateTrueRandom(100, 1000));

📌 API

generateTrueRandom(min, max)

Generates a random integer between min and max (inclusive).

Parameters

| Parameter | Type | Required | Default | |-----------|--------|----------|----------| | min | number | ❌ No | 0 | | max | number | ❌ No | 100 |

⚙️ How It Works

The function combines:

1. A cryptographically secure random number using:

crypto.randomBytes(4)

2. The current timestamp:

Date.now()

Then both values are combined:

value = Date.now() + cryptoRandom

Finally constrained to the given range using modulo:

min + (value % range)

This approach introduces:

• ✅ Cryptographic entropy
• ✅ Time-based entropy
• ✅ Range validation
• ✅ Inclusive bounds

🛡 Validation

The function ensures:

• min and max must be numbers
• min must be less than max

Invalid input will throw an error.

🧪 Example Use Cases

generateTrueRandom(1, 6);      // Dice roll
generateTrueRandom(1000, 9999); // OTP-like number
generateTrueRandom(0, 1);      // Binary random

📂 Project Structure

true-random/
│
├── index.js
├── package.json
│
├── src/
│   ├── generators/
│   │   └── trueRandom.js
│   ├── utils/
│   │   └── validator.js
│   └── constants.js
│
└── test/
    └── test.js

🔄 Versioning

Follows Semantic Versioning:

• PATCH → Bug fixes
• MINOR → New features
• MAJOR → Breaking changes

👨‍💻 Author

Shrey KC

📜 License

MIT License

⭐ Support

If you find this useful:

• ⭐ Star the repository
• 🚀 Share it
• 🛠 Contribute

Built with ❤️ using Node.js