🎲 Rand #

A powerful, intuitive random generator for Dart. Generate random numbers, text, colors, dates, passwords, and more with a clean, ergonomic API.

final name = Rand.fullName();      // → "Emma Rodriguez"
final pass = Rand.password();      // → "k9#Mx!pL2@qR"
final color = Rand.color();        // → CSSColors.coral
final date = Rand.dateTime();      // → 2024-03-15 14:32:07

✨ Features #

📦 Installation #

dependencies:
  rand: ^3.0.0

import 'package:rand/rand.dart';

🚀 Quick Start #

Numbers #

// Integers with named parameters (min defaults to 0)
Rand.integer();                    // 0 to 2^31-1
Rand.integer(max: 100);            // 0 to 100
Rand.integer(min: 50, max: 100);   // 50 to 100

// Floats
Rand.float();                      // 0.0 to double.maxFinite
Rand.float(min: 0, max: 1);        // 0.0 to 1.0

// Boolean with custom probability
Rand.boolean();      // 50% true
Rand.boolean(90);    // 90% true

Text Generation #

Rand.word();              // → "lorem"
Rand.words(count: 5);     // → "amet consectetur adipiscing elit sed"
Rand.sentence();          // → "Lorem ipsum dolor sit amet."
Rand.paragraph(3);        // 3 sentences joined
Rand.article(5);          // 5 paragraphs separated by newlines

Identity #

Rand.firstName();   // → "Olivia"
Rand.lastName();    // → "Thompson"
Rand.fullName();    // → "James Michael Wilson"
Rand.alias();       // → "ShadowHunter"

Cryptographic (Secure RNG) #

// Secure random strings (uses dart:math.Random.secure())
Rand.id();                // → "k9Mx2pLqR8nT4wZy" (16 chars, base62)
Rand.id(32);              // → custom length
Rand.nonce(64);           // → 64-char secure string

// Passwords with options
Rand.password();                           // → "k9#Mx!pL2@qR"
Rand.password(length: 20);                 // longer password
Rand.password(withSpecial: false);         // no special chars
Rand.password(withUppercase: false);       // lowercase + digits only

// Secure bytes
Rand.bytes(32);           // → Uint8List of 32 random bytes
Rand.bytes(32, true);     // secure: true for cryptographic use

Time & Duration #

// Random DateTime (default: 1970-2038)
Rand.dateTime();

// Custom range
Rand.dateTime(DateTime(2020), DateTime(2025));

// By year
Rand.dateTimeYear(2020, 2025);

// Random duration
Rand.duration(Duration(days: 30));                    // 0 to 30 days
Rand.duration(Duration(days: 30), Duration(days: 1)); // 1 to 30 days

Collections #

final fruits = ['🍎', '🍊', '🍋', '🍇', '🍓'];
final scores = {'Alice': 95, 'Bob': 87};

Rand.element(fruits);     // → '🍊'
Rand.subSet(fruits, 3);   // → {'🍎', '🍋', '🍓'}

Rand.mapKey(scores);      // → 'Bob'
Rand.mapValue(scores);    // → 95
Rand.mapEntry(scores);    // → MapEntry('Alice', 95)

Colors #

// All CSS named colors with ARGB values
final color = Rand.color();       // → CSSColors.coral
print(color.name);                // → "coral"
print(color.color);               // → 0xFFFF7F50
print(color.isDark);              // → true

// Filter by brightness
Rand.colorDark();    // dark colors only (good for light backgrounds)
Rand.colorLight();   // light colors only (good for dark backgrounds)

Weighted Random #

Perfect for game mechanics, A/B testing, or any scenario with unequal probabilities:

// Loot box with rarity weights
final loot = Rand.weightedRandomizedArray(
  weights: [1, 10, 100],           // relative probabilities
  pool: ['Legendary', 'Rare', 'Common'],
  size: 10,                        // draw 10 items
);
// → ['Common', 'Common', 'Rare', 'Common', ...]

// Football team composition (weighted positions)
final team = Rand.weightedRandomizedArray(
  weights: [10, 40, 40, 10],
  pool: ['GK', 'DEF', 'MID', 'FWD'],
  size: 11,
);

Nullable Helper #

// 50% chance to return null (useful for test data)
Rand.nullable('value');       // → 'value' or null
Rand.nullable('value', 90);   // 90% null chance

Geo #

Rand.latitude();    // → 42.3601 (range: -90 to 90)
Rand.longitude();   // → -71.0589 (range: -180 to 180)
Rand.city();        // → "Tokyo"

🔧 Advanced Usage #

Seeding for Reproducibility #

// Set seed for reproducible results (great for testing)
Rand.seed(42);
print(Rand.integer(max: 100)); // Always same value for same seed

Secure vs Non-Secure #

📝 Migration from v2.x #

Breaking Changes in v3.0.0 #

Parameter Order Changed - integer() and float() now use named parameters:

// v2.x (DEPRECATED)
Rand.integer(100, 50);    // max, min

// v3.x (NEW)
Rand.integer(min: 50, max: 100);

New Methods - color(), colorDark(), colorLight() - CSS color generation

🤝 Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License #

MIT License - see LICENSE for details.

Made with 🎲 by Mehmet Esen