Illusionist — API Reference

API Overview

Symbol	Purpose	Execution	Common gotcha
`createIllusion`	Create a bound, seeded instance	Sync	Locale is fixed for the instance lifetime
`person.*`	Names, gender, job titles	Sync	Locale-specific datasets (`en`, `de`)
`internet.*`	Emails, URLs, IPs, HTTP metadata	Sync	`ip()` defaults to IPv4
`commerce.*`	Product names, prices	Sync	`price()` returns coins `Money`
`date.*`	Past, future, recent, birthday	Sync	Returns tempo `Temporal` objects
`finance.*`	IBANs, cards, crypto addresses	Sync	IBANs pass mod-97; cards pass Luhn
`location.*`	Cities, streets, GPS	Sync	Locale-specific datasets
`lorem.*`	Words, sentences, paragraphs	Sync	Word pool is fixed
`system.*`	Files, semver, UUIDs, ports	Sync	`port()` avoids well-known ports by default
`createSeed`	Build a `RandomSource` from a seed	Sync	Non-finite numeric seeds throw
`mulberry32`	Low-level 32-bit PRNG	Sync	Not cryptographically secure

Package Entry Point

Import	Purpose
`@vielzeug/illusionist`	`createIllusion`, `Illusionist`, `IllusionistOptions`, `IllusionistLocale`, error classes
`@vielzeug/illusionist/locales`	Tree-shakeable barrel — `en`, `de` locale objects
`@vielzeug/illusionist/locales/en`	English locale object only
`@vielzeug/illusionist/locales/de`	German locale object only
`@vielzeug/illusionist/seed`	`createSeed`, `mulberry32`
`@vielzeug/illusionist/person`	Person category functions
`@vielzeug/illusionist/internet`	Internet category functions
`@vielzeug/illusionist/commerce`	Commerce category functions
`@vielzeug/illusionist/date`	Date category functions
`@vielzeug/illusionist/finance`	Finance category functions
`@vielzeug/illusionist/location`	Location category functions
`@vielzeug/illusionist/lorem`	Lorem category functions
`@vielzeug/illusionist/system`	System category functions

createIllusion

function createIllusion(options: IllusionistOptions): Illusionist;

Creates a bound instance. All categories share one seeded random source and one locale. Locale data is included only when its dedicated subpath is imported; the root entry does not statically import a default locale. For dynamic switching, use await import('@vielzeug/illusionist/locales') before calling this synchronous factory.

Option	Type	Default	Description
`seed`	`number \| string`	`undefined`	Seed for deterministic output. Omit for cryptographic randomness.
`locale`	`IllusionistLocale`	Required	Explicit locale object for locale-aware categories.

Returns: Illusionist — an object with person, internet, commerce, date, finance, location, lorem, system categories, plus seed, locale, dispose(), disposed, disposalSignal, and [Symbol.dispose]().

import { createIllusion } from '@vielzeug/illusionist';
import { en } from '@vielzeug/illusionist/locales';

const illusion = createIllusion({ seed: 12345, locale: en });
illusion.person.fullName();
illusion.dispose();

Person

`person.firstName()`

function firstName(): string;

Returns a random first name from the locale dataset.

`person.lastName()`

function lastName(): string;

Returns a random last name from the locale dataset.

`person.fullName()`

function fullName(): string;

Returns a first and last name separated by a space.

`person.gender()`

function gender(): string;

Returns a random gender label from the locale dataset.

`person.prefix()`

function prefix(): string;

Returns a random name prefix (e.g. Mr., Dr.).

`person.suffix()`

function suffix(): string;

Returns a random name suffix. Returns an empty string when the locale dataset has no suffixes.

`person.jobTitle()`

function jobTitle(): string;

Returns a job area and job type joined by a space.

Internet

`internet.email()`

function email(): string;

Returns an email of the form firstname.lastname@domain.tld.

`internet.username()`

function username(): string;

Returns either a random alphanumeric string or a firstname.lastname pattern.

`internet.password(options?)`

function password(options?: PasswordOptions): string;

Option	Type	Default	Description
`length`	`number`	`12`	Password length.
`memorable`	`boolean`	`false`	Build from name fragments and digits.

Returns a password mixing upper/lowercase letters, digits, and special characters.

`internet.url()`

function url(): string;

Returns a URL of the form protocol://sub.domain.tld/path/....

`internet.domainName()`

function domainName(): string;

Returns a domain of the form domain.tld.

`internet.ip(version?)`

function ip(version?: 4 | 6): string;

Returns an IPv4 or IPv6 address. Defaults to IPv4.

`internet.mac()`

function mac(): string;

Returns a MAC address of the form XX:XX:XX:XX:XX:XX.

`internet.userAgent()`

function userAgent(): string;

Returns a random user agent string.

`internet.httpMethod()`

function httpMethod(): string;

Returns a random HTTP method.

`internet.statusCode()`

function statusCode(): number;

Returns a random HTTP status code.

`internet.mimeType()`

function mimeType(): string;

Returns a random MIME type.

Commerce

`commerce.productAdjective()`

function productAdjective(): string;

Returns a random product adjective.

`commerce.productMaterial()`

function productMaterial(): string;

Returns a random product material.

`commerce.productNoun()`

function productNoun(): string;

Returns a random product noun.

`commerce.productName()`

function productName(): string;

Returns an adjective, material, and noun joined by spaces.

`commerce.department()`

function department(): string;

Returns a random department name.

`commerce.price(options?)`

function price(options?: PriceOptions): Money;

Option	Type	Default	Description
`min`	`number`	`0.01`	Minimum price.
`max`	`number`	`1000`	Maximum price.
`currency`	`'USD' \| 'EUR' \| 'GBP'`	`'USD'`	Currency code.

Returns a coins Money value with two decimal places.

`commerce.productDescription()`

function productDescription(): string;

Returns one or two sentences describing a product.

Date

All date functions return tempo Temporal objects.

`date.past(options?)`

function past(options?: { years?: number; ref?: Temporal.ZonedDateTime }): Temporal.ZonedDateTime;

Returns a date in the past within years (default 1) from ref (default now).

`date.future(options?)`

function future(options?: { years?: number; ref?: Temporal.ZonedDateTime }): Temporal.ZonedDateTime;

Returns a date in the future within years (default 1) from ref (default now).

`date.recent(options?)`

function recent(options?: { days?: number; ref?: Temporal.ZonedDateTime }): Temporal.ZonedDateTime;

Returns a date within days (default 1) in the past from ref (default now).

`date.between(from, to)`

function between(from: Temporal.ZonedDateTime, to: Temporal.ZonedDateTime): Temporal.ZonedDateTime;

Returns a date between from and to. Returns from if from is after to.

`date.birthday(options?)`

function birthday(options?: { minAge?: number; maxAge?: number; ref?: Temporal.ZonedDateTime }): Temporal.PlainDate;

Returns a PlainDate with a random age between minAge (default 18) and maxAge (default 80).

`date.weekday(locale?)`

function weekday(locale?: string): string;

Returns a random weekday name. Uses the instance locale unless overridden.

`date.month(locale?)`

function month(locale?: string): string;

Returns a random month name. Uses the instance locale unless overridden.

Finance

`finance.amount(options?)`

function amount(options?: AmountOptions): Money;

Option	Type	Default	Description
`min`	`number`	`100`	Minimum amount.
`max`	`number`	`10000`	Maximum amount.
`currency`	`'USD' \| 'EUR' \| 'GBP'`	`'USD'`	Currency code.

Returns a coins Money value with two decimal places.

`finance.iban(countryCode?)`

function iban(countryCode?: string): string;

Returns an IBAN. Pass a country code to fix the country; otherwise a random supported country is chosen. The check digits are computed so the IBAN passes mod-97 validation.

`finance.bic()`

function bic(): string;

Returns a BIC/SWIFT code of 8 or 11 characters.

`finance.creditCardNumber(type?)`

function creditCardNumber(type?: 'visa' | 'mastercard' | 'amex'): string;

Returns a card number with a valid Luhn check digit. Amex returns 15 digits; others return 16.

`finance.creditCardCVV(type?)`

function creditCardCVV(type?: 'visa' | 'mastercard' | 'amex'): string;

Returns a CVV. Amex returns 4 digits; others return 3.

`finance.bitcoinAddress()`

function bitcoinAddress(): string;

Returns a Bitcoin address with a 1, 3, or bc1 prefix.

`finance.ethereumAddress()`

function ethereumAddress(): string;

Returns a 42-character Ethereum address prefixed with 0x.

`finance.transactionType()`

function transactionType(): string;

Returns a random transaction type label.

`finance.bank()`

function bank(): string;

Returns a random bank name.

Location

`location.city()`

function city(): string;

Returns a random city from the locale dataset.

`location.street()`

function street(): string;

Returns a random street from the locale dataset.

`location.streetAddress()`

function streetAddress(): string;

Returns a house number (1–999) followed by a street name.

`location.zipCode()`

function zipCode(): string;

Returns a ZIP code matching the locale's pattern.

`location.state()`

function state(): string;

Returns a random state or region from the locale dataset.

`location.country()`

function country(): string;

Returns a random country from the locale dataset.

`location.latitude()`

function latitude(): number;

Returns a latitude in the range [-90, 90].

`location.longitude()`

function longitude(): number;

Returns a longitude in the range [-180, 180].

`location.nearbyGPSCoordinate(ref?)`

function nearbyGPSCoordinate(ref?: Coordinate): Coordinate;

Returns a coordinate within ~1 degree of ref. When ref is omitted, a random coordinate is used as the base.

Lorem

`lorem.word()`

function word(): string;

Returns a single random word.

`lorem.words(count?)`

function words(count?: number): string;

Returns count (default 3) space-joined words.

`lorem.sentence(wordCount?)`

function sentence(wordCount?: number): string;

Returns a sentence of wordCount words (default 6–12) with a capital first letter and trailing period.

`lorem.sentences(count?)`

function sentences(count?: number): string;

Returns count (default 3) space-joined sentences.

`lorem.paragraph(sentenceCount?)`

function paragraph(sentenceCount?: number): string;

Returns a paragraph of sentenceCount sentences (default 3–7).

`lorem.paragraphs(count?)`

function paragraphs(count?: number): string;

Returns count (default 3) newline-joined paragraphs.

`lorem.slug(wordCount?)`

function slug(wordCount?: number): string;

Returns a hyphen-joined slug of wordCount (default 3) words.

`lorem.lines(count?)`

function lines(count?: number): string;

Returns count (default 5) newline-joined lines, each a sentence.

System

`system.fileExtension()`

function fileExtension(): string;

Returns a random file extension.

`system.fileName()`

function fileName(): string;

Returns a random file name with extension.

`system.filePath()`

function filePath(): string;

Returns a path with 1–4 directory segments and a file name.

`system.mimeType()`

function mimeType(): string;

Returns a random MIME type.

`system.semver(options?)`

function semver(options?: { maxMajor?: number; includePrerelease?: boolean }): string;

Option	Type	Default	Description
`maxMajor`	`number`	`20`	Maximum major version.
`includePrerelease`	`boolean`	`false`	Occasionally append a prerelease label.

Returns a semver string.

`system.uuid()`

function uuid(): string;

Returns a random UUID via crypto.randomUUID(). Not deterministic — ignores the seeded RandomSource. Use only when uniqueness matters more than reproducibility.

`system.port(options?)`

function port(options?: { min?: number; max?: number }): number;

Option	Type	Default	Description
`min`	`number`	`1024`	Minimum port.
`max`	`number`	`65535`	Maximum port.

Returns a random port number.

`system.cron()`

function cron(): string;

Returns a random cron expression from common patterns.

`system.process()`

function process(): string;

Returns a random process name of the form prefix_suffix.

Seed

Import from the seed subpath:

import { createSeed, mulberry32 } from '@vielzeug/illusionist/seed';

`createSeed(seed?)`

function createSeed(seed?: number | string): RandomSource;

Creates a RandomSource from a seed. Number seeds are used directly as mulberry32 state. String seeds are hashed to a 32-bit integer. Omit the seed for cryptographic randomness via crypto.getRandomValues. Throws IllusionistSeedError for non-finite numeric seeds.

const a = createSeed(12345);    // deterministic
const b = createSeed('hello');  // deterministic (hashed)
const c = createSeed();         // cryptographic

`mulberry32(seed)`

function mulberry32(seed: number): RandomSource;

Low-level 32-bit PRNG. Not cryptographically secure. Returns a RandomSource producing floats in [0, 1).

Types

type PersonLocaleData = {
  readonly firstNameFemale: readonly string[];
  readonly firstNameMale: readonly string[];
  readonly gender: readonly string[];
  readonly jobAreas: readonly string[];
  readonly jobTypes: readonly string[];
  readonly lastName: readonly string[];
  readonly prefix: readonly string[];
  readonly suffix: readonly string[];
};

type LocationLocaleData = {
  readonly cities: readonly string[];
  readonly countries: readonly string[];
  readonly states: readonly string[];
  readonly streets: readonly string[];
  readonly zipPattern: string;
};

type IllusionistLocale = {
  readonly code: string;
  readonly person: PersonLocaleData;
  readonly location: LocationLocaleData;
};

type IllusionistOptions = {
  seed?: number | string;
  locale: IllusionistLocale;
};

type Illusionist = {
  readonly person: typeof person;
  readonly internet: typeof internet;
  readonly commerce: typeof commerce;
  readonly date: typeof date;
  readonly finance: typeof finance;
  readonly location: typeof location;
  readonly lorem: typeof lorem;
  readonly system: typeof system;
  readonly seed: number | string | undefined;
  readonly locale: IllusionistLocale;
  dispose(): void;
  readonly disposed: boolean;
  readonly disposalSignal: AbortSignal;
  [Symbol.dispose](): void;
};

type Coordinate = {
  lat: number;
  lng: number;
};

type PasswordOptions = {
  length?: number;
  memorable?: boolean;
};

type PriceOptions = {
  readonly min?: number;
  readonly max?: number;
  readonly currency?: 'USD' | 'EUR' | 'GBP';
};

type AmountOptions = {
  readonly min?: number;
  readonly max?: number;
  readonly currency?: 'USD' | 'EUR' | 'GBP';
};

// Re-exported from @vielzeug/arsenal
type RandomSource = {
  next(): number; // float in [0, 1)
};

Errors

All errors extend IllusionistError, which extends Error. Use instanceof IllusionistError to catch any illusionist-originated error.

Error	Trigger	Notable properties
`IllusionistError`	Base class for all illusionist errors	`name`, `message`
`IllusionistSeedError`	Non-finite numeric seed passed to `createSeed` (`NaN`, `Infinity`, `-Infinity`)	`name`, `message`

import { IllusionistError, IllusionistSeedError, createSeed } from '@vielzeug/illusionist';

try {
  createSeed(Number.NaN);
} catch (error) {
  if (error instanceof IllusionistSeedError) {
    console.log(error.message);
  }
}

API Overview ​

Package Entry Point ​

createIllusion ​

Person ​

person.firstName() ​

person.lastName() ​

person.fullName() ​

person.gender() ​

person.prefix() ​

person.suffix() ​

person.jobTitle() ​

Internet ​

internet.email() ​

internet.username() ​

internet.password(options?) ​

internet.url() ​

internet.domainName() ​

internet.ip(version?) ​

internet.mac() ​

internet.userAgent() ​

internet.httpMethod() ​

internet.statusCode() ​

internet.mimeType() ​

Commerce ​

commerce.productAdjective() ​

commerce.productMaterial() ​

commerce.productNoun() ​

commerce.productName() ​

commerce.department() ​

commerce.price(options?) ​

commerce.productDescription() ​

Date ​

date.past(options?) ​

date.future(options?) ​

date.recent(options?) ​

date.between(from, to) ​

date.birthday(options?) ​

date.weekday(locale?) ​

date.month(locale?) ​

Finance ​

finance.amount(options?) ​

finance.iban(countryCode?) ​

finance.bic() ​

finance.creditCardNumber(type?) ​

finance.creditCardCVV(type?) ​

finance.bitcoinAddress() ​

finance.ethereumAddress() ​

finance.transactionType() ​

finance.bank() ​

Location ​

location.city() ​

location.street() ​

location.streetAddress() ​

location.zipCode() ​

location.state() ​

location.country() ​

location.latitude() ​

location.longitude() ​

location.nearbyGPSCoordinate(ref?) ​

Lorem ​

lorem.word() ​

lorem.words(count?) ​

lorem.sentence(wordCount?) ​

lorem.sentences(count?) ​

lorem.paragraph(sentenceCount?) ​

lorem.paragraphs(count?) ​

lorem.slug(wordCount?) ​

lorem.lines(count?) ​

System ​

system.fileExtension() ​

system.fileName() ​

system.filePath() ​

system.mimeType() ​

system.semver(options?) ​

system.uuid() ​

system.port(options?) ​

system.cron() ​

system.process() ​

Seed ​

createSeed(seed?) ​