IllusionistData

Typed, deterministic, locale-aware fake data generator with a seeded PRNG, eight data categories, and zero external runtime dependencies.

Version

v2.2.0

Size

9.8 KB gzip

Runtime support

BrowserNode ≥22SSR

Key exports

createIllusioncreateSeedmulberry32

Works well with

arsenal coins tempo

Why Illusionist?

Illusionist generates realistic fake data from a single seeded random source. The same seed always produces the same output, so test fixtures and snapshots stay reproducible across runs, machines, and CI. Every category shares one bound instance with one locale, so a person, their email, and their address stay internally consistent.

// Before
const user = {
  name: 'Test User',
  email: 'test@example.com',
  address: '123 Main St',
};

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

const illusion = createIllusion({ seed: 12345, locale: en });

const user = {
  name: illusion.person.fullName(),
  email: illusion.internet.email(),
  address: illusion.location.streetAddress(),
};

illusion.dispose();

Feature	Illusionist	Faker.js	@faker-js/faker
Bundle size	9.8 KB	External dependency	External dependency
Zero external dependencies
Seeded determinism		Partial
Locale-aware datasets
TypeScript-native types

Use Illusionist when test fixtures, mock APIs, or database seeds must be realistic and reproducible from a single seed value.

Consider @faker-js/faker when you need a large catalog of locale datasets beyond en and de or a community plugin ecosystem.

Installation

pnpm

pnpm add @vielzeug/illusionist

npm

npm install @vielzeug/illusionist

yarn

yarn add @vielzeug/illusionist

Quick Start

Create a bound instance with a seed and locale. All categories share that seed, so output is deterministic.

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

const illusion = createIllusion({ seed: 12345, locale: en });

illusion.person.fullName();        // 'Ashley Harris'
illusion.internet.email();         // 'samantha.sanchez@mail.com'
illusion.commerce.price();         // Money { amount: 76640n, currency: USD }
illusion.date.past({ years: 2 });  // Temporal.ZonedDateTime

illusion.dispose();                // release the instance; [Symbol.dispose]() also works

Features

• person: names, gender, prefixes, suffixes, job titles
• internet: emails, usernames, passwords, URLs, IPs, MACs, HTTP metadata
• commerce: product names, departments, prices as coins Money
• date: past, future, recent, between, birthday as tempo Temporal objects
• finance: amounts, IBANs, BICs, credit cards, crypto addresses
• location: cities, streets, states, countries, GPS coordinates
• lorem: words, sentences, paragraphs, slugs
• system: file paths, semver, UUIDs, ports, cron expressions

Documentation

• Usage Guide
• API Reference
• Examples

See Also

• Arsenal — random primitives (RandomSource, uuid) that Illusionist builds on.
• Coins — exact money type returned by commerce.price() and finance.amount().
• Tempo — Temporal date utilities returned by every date function.