randino 1.3.1

Generates random person names, nicknames, words, sentences, real locations, ages, genders and fictional organizations in nine languages. No dependencies, pure Dart.

randino for Dart

📘 randino.cdget.com

Every option and every example, with Dart picked in the sidebar. This README is just the quick start.

---

randino generates random person names, nicknames, words, sentences, real locations, ages, genders and organizations in the language you ask for.

• Person names read like names people carry: Emma Clover, Jack Reeves, each with its English pronunciation. 9 languages.
• Nicknames are handles for a game or a website: MistyOwl, CraneVoyage, RustyBoot. Built from everyday words across twenty-nine themes, and never from person names.
• Words are those twenty-nine themes on their own: randWord, plus randAnimal, randFood and twenty-seven more.
• Sentences are whole statements in the language's own grammar, from randSentence. The verb decides what can stand beside it, so the words of one sentence belong together.
• Locations are real places down to a neighbourhood or a city, from randLocation: Korean and US divisions, as each country publishes them.
• Ages are whole numbers drawn along a curve shaped like a population, from randAge, so a sample of people is mostly adults.
• Genders are the labels a form in the language writes, from randGender: 여성, Female, Weiblich. An unstated gender and a third gender are there when you ask for them.
• Organizations are companies, schools, offices and associations that do not exist, from randOrganization: (주)새솔테크, Westbrook High School, Stadtwerke Bergtal.
• Decorators attach something to a string you already have: randSuffix, randPrefix and randModifier.
• Every parameter is named and optional, and a null enum means "every one of them", so randName() on its own works.
• Pure Dart, no dependencies. It imports nothing but dart:math, so it runs on the VM, on the web and inside Flutter on every platform.
• Every generator and decorator takes a random. Random.secure() for a value nobody may predict, Random(42) for one that has to come out the same every run.

This is the Dart package. The npm package and the PyPI package are the other two, and all three generate from the same datasets under the same rules. They version independently, so the numbers on pub.dev, npm and PyPI will not always agree.

Install

dart pub add randino

Requires Dart 3.7 or newer (Flutter 3.29). There is nothing else to install.

Person names

import 'package:randino/randino.dart';

randName();
// ['Emma Clover']

randName(language: NameLanguage.en, count: 3);
// ['Christina Mills', 'Jack Reeves', 'Brian Wallace']

randName(language: NameLanguage.ko, script: NameScript.roman);
// ['Kim Minjun']

randName(
  language: NameLanguage.en,
  gender: NameGender.female,
  includeMiddleName: true,
);
// ['Grace Amelia Bennett']

randNameDetails(language: NameLanguage.ko).first;
// NameDetail(여미주, Yeo Miju, ko, female)

Parameter	Type	Default
language	NameLanguage?	null — every one
gender	NameGender?	null — one per name
count	int	1
realism	RandRealism	RandRealism.real
minLength / maxLength	int?	language
includeSurname	bool	true
includeMiddleName	bool	false
script	NameScript	NameScript.native
startsWith	String?	null
unique	bool	false

randNameDetails takes the same parameters except script, and returns a NameDetail for each name, carrying native, roman, language and gender.

Nicknames

randNickname(language: WordLanguage.en, count: 3);
// ['FoggyHillside', 'CraneVoyage', 'TinyLeopardCloak']

randNickname(language: WordLanguage.en, theme: WordTheme.animal, count: 2);
// ['FloatingFalcon', 'ChewyOtter']

randNickname(language: WordLanguage.en, slots: {WordSlot.action}, count: 2);
// ['CountingHarmonics', 'HaulingBurrito']

randNicknameDetails(language: WordLanguage.en).first;
// NicknameDetail(MistyOwl, [Misty, Owl], en, animal)

Parameter	Type	Default
language	WordLanguage?	null — every one
theme	WordTheme?	null — every one
slots	Set<WordSlot>?	null — every shape
count	int	1
realism	RandRealism	RandRealism.real
vocabulary	RandVocabulary	RandVocabulary.full
minLength / maxLength	int?	language
wordSeparator	String?	language
startsWith	String?	null
unique	bool	false

Themes: animal, object, nature, plant, gem, concept, myth, job, music, place, food, sport, vehicle, product, color, finance, tech, weather, space, time, emotion, body, clothing, tool, drink, toy, sound, person, furniture.

Words

The pools the nicknames are built from, on their own. Twenty-nine themes, nine languages, and a function per theme.

randWord(language: WordLanguage.en, theme: WordTheme.animal, count: 3);
// [Otter, Falcon, Lynx]

randAnimal(language: WordLanguage.en, count: 2); // [Turtle, Crane]
randFood(language: WordLanguage.en, count: 2); // [Dumpling, Cocoa]

randWordDetails(language: WordLanguage.en, theme: WordTheme.plant).first;
// WordDetail(Cedar, en, plant)

wordLengthRange(language: WordLanguage.en); // LengthRange(3, 11)

Parameter	Type	Default
language	WordLanguage?	null — every one
theme	WordTheme?	null — every one
count	int	1
realism	RandRealism	RandRealism.real
vocabulary	RandVocabulary	RandVocabulary.full
minLength / maxLength	int?	pools
startsWith	String?	null
unique	bool	false

One function per theme: randAnimal, randObject, randNature, randPlant, randGem, randConcept, randMyth, randJob, randMusic, randPlace, randFood, randSport, randVehicle, randProduct, randColor, randFinance, randTech, randWeather, randSpace, randTime, randEmotion, randBody, randClothing, randTool, randDrink, randToy, randSound, randPerson, randFurniture. They return List<String>; for the detail form, pass the theme to randWordDetails.

Sentences

Whole statements, written the way the language writes them. The nouns are the same pools the words and nicknames come from, and what a sentence adds is the grammar: a verb that states what can do it and what it can be done to, and the shapes each language allows.

randSentence(language: WordLanguage.en, count: 3);
// [The brave lion runs quietly., The otter swims in the cove., The sky is blue.]

randSentence(language: WordLanguage.ko, count: 2);
// [검은 고양이가 숲에서 잠잔다., 여우가 사과를 먹는다.]

randSentence(language: WordLanguage.en, shape: SentenceShape.simple);
// [The gondola passes.]
randSentence(language: WordLanguage.en, include: <String>['brave', 'lion']);
// [The brave lion yawns quietly.]

randSentenceDetails(language: WordLanguage.ko).first;
// SentenceDetail(검은 고양이가 숲에서 잠잔다., [검은 고양이, 숲, 잠잔다], ko, animal)

sentenceLengthRange(WordLanguage.en); // LengthRange(12, 92)

Parameter	Type	Default
language	WordLanguage?	null — every one
theme	WordTheme?	null — every one
shape	SentenceShape?	null — every one
slots	Set<SentenceSlot>?	null — every one
include	List<String>	const []
type	Set<SentenceType>?	null — drawn
quote	SentenceQuote?	null
style	SentenceStyle?	null — drawn
sentences	int	1
includeName	bool?	null — drawn
count	int	1
realism	RandRealism	RandRealism.real
vocabulary	RandVocabulary	RandVocabulary.common
minLength / maxLength	int?	language
startsWith	String?	null
unique	bool	false

slots names the parts a shape may carry beside its subject: object, place, time, manner, state, quantity, money, date, clock, or an empty set for a subject and its predicate alone. A language declares its own shapes, so German has no object and Russian no place, because both would mark those with a case their nouns have to change for. Asking for one falls back to the closest shape the language does have.

include puts words you name into every sentence. A word the pools hold goes in the phrase it belongs to, and a word from anywhere else is used as a noun.

type is what the sentence does: a statement, a question, an exclamation, a line that trails off, or one somebody says or thinks. style is the speech level, which Korean writes four of. sentences puts up to ten of them in one string, about one subject. includeName puts a generated person's name where a person can stand. Left out, the three of them are drawn per result.

Locations

Real places, written out from the country down the way the language writes one. Every division is one the country itself publishes, inside the one written beside it, and nothing goes below a Korean 읍·면·동 or a US city, so a result is never somebody's address. Korean and English only: a country is in when its list comes with no conditions a user of this package would inherit.

randLocation(language: LocationLanguage.ko, count: 2);
// [대한민국 경기도 양평군 단월면, 대한민국 충청북도 청주시 서원구 미평동]
randLocation(language: LocationLanguage.en, level: LocationLevel.city);
// [Gig Harbor, Washington, United States]

randRegion(language: LocationLanguage.en, count: 3); // [Idaho, Georgia, Vermont]
randCity(language: LocationLanguage.ko, count: 3); // [함안군, 영덕군, 여수시]
randDistrict(count: 3); // [가현동, 겸면, 행주외동]

randCityDetails(language: LocationLanguage.ko).first;
// LocationDetail(중랑구, ko, city, 대한민국, 서울특별시, 중랑구, null)

Parameter	Type	Default
language	LocationLanguage?	null — every one
level	LocationLevel	LocationLevel.district
includeCountry	bool	true
count	int	1
minLength / maxLength	int?	null
startsWith	String?	null
unique	bool	false

level is how far down the location goes: country, region, city or district. A country without that level stops at the deepest one it has, so an English location ends at its city. includeCountry: false leaves the country out of the string, which is what a fixed language usually wants. randRegion, randCity and randDistrict take the same parameters minus level, and hand back that one division's name; each has a …Details twin, as randLocation has randLocationDetails. randCountry is the exception: it takes a WordLanguage? and names any of the 249 ISO 3166-1 countries and territories in any of the nine languages, and randCountryDetails adds each one's code as a CountryDetail.

Ages

Ages for sample people, in whole years. The draw follows a curve shaped like a population rather than an even spread: it peaks from 25 to 35, sits lower for children and falls away past seventy, so a third of the ages are in their twenties and thirties and about 2% are past eighty.

randAge(count: 5); // [27, 8, 41, 63, 30]
randAge(minAge: 18, maxAge: 39, count: 3); // [22, 35, 31]
randAge(group: {AgeGroup.teen, AgeGroup.senior}, count: 3); // [15, 71, 66]
randAge(distribution: AgeDistribution.uniform, count: 3); // [91, 4, 57]

randAgeDetails().first; // AgeDetail(16, teen)

Parameter	Type	Default
minAge / maxAge	int?	0 / 100
group	Set<AgeGroup>?	null — every group
distribution	AgeDistribution	AgeDistribution.population
count	int	1
unique	bool	false

group is child (0 to 12), teen (13 to 19), adult (20 to 64) or senior (65 and up), and narrows the range rather than replacing it. An age has no language, so randAge takes none.

Genders

Genders for sample people, written the way a form in the language labels them. Male and female split evenly; includeUnknown adds a gender nobody stated, about one draw in eleven, and includeNonbinary a third gender, about one in a hundred.

randGender(language: WordLanguage.ko, count: 3); // [여성, 남성, 여성]
randGender(language: WordLanguage.en, includeUnknown: true, count: 3); // [Male, Unknown, Female]
randGender(language: WordLanguage.de, includeNonbinary: true); // [Divers]

randGenderDetails(language: WordLanguage.ko).first; // GenderDetail(여성, female, ko)

Parameter	Type	Default
language	WordLanguage?	null — every one
includeUnknown	bool	false
includeNonbinary	bool	false
count	int	1
unique	bool	false

A GenderDetail's code is a GenderCode whatever the language, and its male and female are the two NameGender holds.

Organizations

Companies, schools, government offices, public institutions and associations that do not exist, each written the way its language writes that kind of organization. A company may carry its legal form (Inc., (주), GmbH, ООО), and the stems are chosen to be nobody's brand.

randOrganization(language: WordLanguage.ko, count: 3); // [(주)가람에너지, 윤슬교육지원청, 새솔홀딩스]
randOrganization(language: WordLanguage.en, industry: OrganizationIndustry.logistics);
// [Greenbriar Logistics Corp.]
randOrganization(
  language: WordLanguage.de,
  type: {OrganizationType.school, OrganizationType.public},
  count: 2,
);
// [Gymnasium Eschenhain, Stadtbibliothek Tannenhof]

randOrganizationDetails(language: WordLanguage.ko, type: {OrganizationType.company}).first;
// OrganizationDetail((주)새솔테크, 새솔테크, (주), company, tech, ko)

Parameter	Type	Default
language	WordLanguage?	null — every one
type	Set<OrganizationType>?	null — every kind
industry	OrganizationIndustry?	null — every one
includeLegalForm	bool?	null — drawn
count	int	1
realism	RandRealism	RandRealism.real
minLength / maxLength	int?	null
startsWith	String?	null
unique	bool	false

A null type draws a kind per result, companies most often. An industry is written into a company's name as a word for its business, and naming one with type left null asks for companies. RandRealism.invented builds the stem from the language's own sounds, for a name nobody has.

Decorators

randSuffix, randPrefix and randModifier attach something to a string you already have, rather than generating one. They take anything, not just this library's output, which is why none of them is a parameter on a generator. Each of them also works with no value at all, handing back the thing it would have attached.

randSuffix(value: 'MistyOwl'); // 'MistyOwl_nVtRC'
randSuffixAll(randNickname(language: WordLanguage.en, count: 2));
// [RoundSeason_RVBnC, RowdyDusk_dwtu5]

randPrefix(value: 'order-4021', length: 4, separator: '-'); // 'k3Rm-order-4021'
randSuffix(value: 'MistyOwl', length: 8, charset: '0123456789'); // 'MistyOwl_40218836'
randSuffix(); // 'nVtRC' — the token on its own

Parameter	Type	Default
length	int	5
separator	String	'_'
charset	String?	built-in

A fresh token per value, never one for the batch. The default charset leaves out 0O1lI, because these end up in names people read aloud and type back in. The …All forms are Dart's answer to a signature the other two packages write as String | List<String>, and value is named rather than positional because Dart cannot make a positional parameter optional alongside named ones.

randModifier attaches a word instead of a token, in front of any string:

randModifier(value: 'Owl'); // 'MistyOwl'
randModifier(value: 'Owl', separator: ' '); // 'Misty Owl'
randModifier(value: 'Owl', kind: ModifierKind.action); // 'CountingOwl'
randModifier(); // 'Misty'

randModifierAll(randAnimal(language: WordLanguage.en, count: 2));
// [TwinklingLynx, OnyxCrane]

Parameter	Type	Default
value	String?	null
language	WordLanguage?	script
realism	RandRealism	RandRealism.real
kind	ModifierKind?	null
separator	String?	language

With no language, the script of the value picks one, so '고양이' is never handed an English modifier.

Helpers and constants

nameLengthRange(language: NameLanguage.ko); // LengthRange(2, 3)
nameLengthRange(language: NameLanguage.en, includeMiddleName: true); // LengthRange(11, 32)
nameSupportsMiddleName(NameLanguage.ko); // false
nameSupportsRoman(NameLanguage.en); // false
nicknameLengthRange(language: WordLanguage.ko); // LengthRange(1, 13)
sentenceLengthRange(WordLanguage.ko); // LengthRange(5, 43)

nameLanguages, wordLanguages, wordThemes, locationLanguages, locationLevels, ageGroups, organizationTypes and organizationIndustries list what the generators accept; randCountMax, randLengthMin / Max, randSentenceLengthMax, randLocationLengthMax, randAgeMax, randOrganizationLengthMax, affixLengthDefault / Max, affixSeparatorDefault and affixCharset are the bounds and defaults every parameter is clamped to.

Differences from the npm package

The two generate the same output from the same data, and only the surface is Dart's rather than JavaScript's.

npm	pub.dev
One options object	Named parameters
language: 'ko'	language: NameLanguage.ko
language: 'all' (the default)	language left out, or null
[number, number]	LengthRange, which compares by value
NameDetail / NicknameDetail interfaces	The same two names, as classes
output: 'detail'	randNameDetails / randNicknameDetails / randWordDetails / randSentenceDetails / randLocationDetails …
randModifier('Owl')	randModifier(value: 'Owl') — every parameter is named
randSuffix(['a', 'b'])	randSuffixAll(['a', 'b'])
include: 'lion' or ['lion']	include: ['lion'] — a list either way

The last two are the same limitation twice: Dart has neither overloads nor union types, so one function cannot return List<String> for one argument and List<NameDetail> for another. Where npm and PyPI pick the shape with an option, pub.dev picks it with a second function.

Development

dart pub get
dart test
dart analyze
dart format .

License

MIT © CDGet