@razomy/random

Npm | Npmx | GitHub | Io

Utility functions for safely generating random numbers, strings, and arbitrary values

🚀 Start

Install

npm i @razomy/random

Import

import * as random from '@razomy/random';
// or
import { create_lorem } from '@razomy/random';

📑 Table of Contents

Functions

• create_lorem
• createCssGradient
• createDate
• createFloat
• createFloatRange
• createGuid
• createInt
• createIpv4
• createLightHexColor
• createMac
• createPassword
• createPinCode
• createRecoveryKeys
• createString
• createUuid
• isYesOrNo
• pickItem
• rollDice
• shuffleArray
• splitIntoGroups

📚 Documentation

Functions

create_lorem

create_lorem(wordCount: number): string

Generates random Lorem Ipsum text. Generates a random sequence of Lorem Ipsum words of the specified length. The resulting string is capitalized and ends with a period.

Examples

createLorem(3); // Dolor sit amet.

createLorem(5); // Elit sed do eiusmod tempor.

createLorem(1); // Consectetur.

createCssGradient

createCssGradient(): string

Create a random CSS linear gradient string. Generates a CSS linear-gradient with a random angle (0–360°) and two random hex colors.

Examples

createCssGradient(); // linear-gradient(142deg, #a3f0b1, #0d44ec)

createCssGradient(); // linear-gradient(0deg, #000000, #ffffff)

createCssGradient(); // linear-gradient(270deg, #ff6347, #4682b4)

createDate

createDate(startYear: number, endYear: number): string

Create a random date string within a year range. Generates a random date between the start of startYear and the end of endYear, returning it as a formatted string in YYYY-MM-DD HH:mm:ss format.

Examples

createDate(); // e.g. 2015-07-23 14:05:32

createDate(2020, 2020); // e.g. 2020-09-11 03:42:17

createDate(1990, 2000); // e.g. 1994-02-08 21:30:44

createFloat

createFloat(): number

Create a cryptographically secure random float in [0, 1). Generates a random floating-point number between 0 (inclusive) and 1 (exclusive) using the Web Crypto API for cryptographic randomness.

Examples

createFloat(); // 0.7382194561

createFloat(); // 0.0231587943

createFloat(); // 0.9481726350

createFloatRange

createFloatRange(from: number, to: number): number

Generate a random float within a specified range [from, to). Creates a random floating-point number between from (inclusive) and to (exclusive) using uniform distribution.

Examples

createFloatRange(0, 1); // 0.7234...

createFloatRange(-5, 5); // -2.318...

createFloatRange(100, 200); // 142.857...

createGuid

createGuid(): string

Create a RFC4122-like GUID string. Generates a 32-hex-character GUID formatted as xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Examples

createGuid(); // a3f1b2c4-d5e6-f7a8-b9c0-d1e2f3a4b5c6

createGuid(); // 1b4e28ba-2fa1-11d2-883f-b9a761bde3fb

const id = createGuid();
id.length; // 36

createInt

createInt(min: number, max: number): number

Generate a random integer within a range. Generates a random integer between min (inclusive) and max (inclusive) using a uniform distribution.

Examples

createInt(); // 42 (random integer between 0 and 100)

createInt(1, 10); // 7 (random integer between 1 and 10)

createInt(-5, 5); // -3 (random integer between -5 and 5)

createIpv4

createIpv4(): string

Generate a random IPv4 address string. Creates a random IPv4 address by generating four random integers in the range [0, 255] and joining them with dots.

Examples

createIpv4(); // 192.168.1.42

createIpv4(); // 10.0.254.3

createIpv4(); // 0.127.255.12

createLightHexColor

createLightHexColor(): string

Create a random light hex color string. Generates a random hex color in the light spectrum by constraining each RGB channel to the range [127, 255], producing pastel/light colors.

Examples

createLightHexColor(); // #a3f0c7

createLightHexColor(); // #e2b4ff

createLightHexColor(); // #7ff89d

createMac

createMac(): string

Create a random MAC address. Generates a random MAC address string in uppercase with colon-separated octets.

Examples

createMac(); // A3:4F:B2:00:CC:91

createMac(); // 0E:7D:3A:F1:58:C4

createMac(); // FF:12:9B:6E:D0:47

createPassword

createPassword(length: number): string

Create a random password. Generates a random password of the specified length containing at least one uppercase letter, one lowercase letter, one digit, and one special character. The result is shuffled to avoid predictable positions.

Examples

createPassword(); // aG3!xK9@mNq#pR7& (16 characters)

createPassword(4); // k2A! (4 characters, one from each group)

createPassword(32); // xP4!rQ8@wN2#mK7&jL5$tH9^yB1*zF6+ (32 characters)

createPinCode

createPinCode(length: number): string

Create a random PIN code of a given length with no consecutive repeated digits. Generates a numeric PIN code string of the specified length (default 6). Each digit is randomly chosen from 0–9, ensuring no two consecutive digits are the same.

Examples

createPinCode(); // 482973 (6-digit PIN, no consecutive repeats)

createPinCode(4); // 3917 (4-digit PIN, no consecutive repeats)

createPinCode(1); // 7 (single-digit PIN)

createRecoveryKeys

createRecoveryKeys(count: number, blocks: number, blockLength: number): string[]

Create an array of recovery keys. Generates a list of recovery keys, each composed of uppercase alphanumeric blocks separated by dashes.

Examples

createRecoveryKeys(1, 2, 3); // [A7K-9BZ]

createRecoveryKeys(2); // [AXRF-K9B2-QLMZ-7TYP, JN3W-8DVE-0HCS-4FRA]

createRecoveryKeys(3, 3, 5); // [AX7RF-K9BQ2-LMZTK, JN3W8-DVE0H-CS4FR, PL9YT-QWE3R-ZXC7V]

createString

createString(length: number, characters: string): string

Generates a random string. Generates a random string of specified length using optional custom characters.

Examples

randomString(3); // X7z

randomString(5, '01'); // 10101

randomString(4, 'a'); // aaaa

createUuid

createUuid(): string

Create a UUID v4 string. Generates a cryptographically random UUID v4 string using the Web Crypto API.

Examples

createUuid(); // a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d

createUuid(); // 550e8400-e29b-41d4-a716-446655440000

const id = createUuid();
id.length; // 36

isYesOrNo

isYesOrNo(): boolean

Randomly returns true or false with equal probability. Generates a random float and returns true if it exceeds 0.5, false otherwise.

Examples

isYesOrNo(); // true

isYesOrNo(); // false

const answer: boolean = isYesOrNo(); // true | false

pickItem

pickItem(array: readonly T[]): T

Pick a random item from a non-empty array. Selects and returns a single random element from the provided array using a uniform random integer generator.

Examples

pickItem([1, 2, 3]); // 2 (random)

pickItem(['a', 'b', 'c', 'd']); // c (random)

pickItem([true]); // true

rollDice

rollDice(diceCount: number, sides: number): number[]

Roll one or more dice and return the results. Simulates rolling a specified number of dice, each with a given number of sides, returning an array of random integer results.

Examples

rollDice(); // [3, 5] (two six-sided dice)

rollDice(1, 20); // [14] (one twenty-sided die)

rollDice(4, 6); // [2, 6, 1, 4] (four six-sided dice)

shuffleArray

shuffleArray(array: T[]): T[]

Shuffle an array using the Fisher-Yates algorithm. Creates a new array with elements randomly shuffled using the Fisher-Yates algorithm. The original array is not modified.

Examples

shuffleArray([1, 2, 3, 4, 5]); // [3, 1, 5, 2, 4]

shuffleArray(['a', 'b', 'c']); // [c, a, b]

shuffleArray([42]); // [42]

splitIntoGroups

splitIntoGroups(array: T[], groupsCount: number): T[][]

Split an array into a specified number of groups with randomly distributed elements. Shuffles the input array and distributes elements round-robin into the specified number of groups. The original array is not mutated.

Examples

splitIntoGroups([1, 2, 3, 4], 2); // e.g. [[3, 1], [4, 2]]

splitIntoGroups(['a', 'b', 'c'], 3); // e.g. [[b], [c], [a]]

splitIntoGroups([10, 20, 30, 40, 50], 2); // e.g. [[30, 50, 10], [20, 40]]

🕊️ Vision

"Razomy" means Together—you and me.
We act as catalysts, turning natural chaos into clarity through open collaboration.
By building honest, reliable systems, we empower humanity and create a foundation for peace.
We foster a borderless environment driven by quality code and mutual support.
Join us to build this future—one commit at a time.

💖 Fuel Our Shared Future

We can't build this without you. If this library has saved you time or helped turn chaos into clarity in your own projects, please consider backing the developers behind it. Building reliable, open-source tools takes immense time and energy. Your sponsorship isn't just a donation; it’s the fuel that keeps this project actively maintained, bug-free, and thriving for everyone who relies on it.

Help us keep the momentum going. Choose how you want to light the way:

• ✨ Spark of Creativity
• 🌟 Flame of Innovation (Recommended)
• 🔥 Torch of Progress
• 🚀 Beacon of Excellence

🤝 Contributing

Contributions, issues and feature requests are welcome! Feel free to check issues page.

📝 License

Copyright © 2026 Razomy. This project is MIT licensed.

🐛 Reporting Issues

We use GitHub Issues as the official bug tracker for this project.

Before opening a new issue, please check if your problem has already been reported. If it hasn't, please open a new issue here: GitHub Issues: razomy/js

When reporting a bug, please include:

• A brief description of the issue.
• Steps to reproduce the bug.
• Your current environment (Node version, OS, etc.).