@dasmig/persona

Complete fictional characters from one seeded call: name, country, city, birth date and age, body, personality, religion, hobbies, favourite media and job. It is persona-generator (C++23) compiled to WebAssembly, with the lite data of the eight libraries it composes built in, so nothing is fetched at run time but the module's own persona.wasm.

The output is fictional sample data, not a description or prediction of a real person.

import { createPersonaGenerator } from '@dasmig/persona';

createPersonaGenerator().then(personas => {
  const p = personas.generate({ country: 'BR', sex: 'female', ages: { min: 25, max: 40 } });
  console.log(p.name, p.age, p.city.name, p.occupation.job?.label);

  // The same seed, request and data give the same persona, on every platform.
  const again = personas.generate({ country: 'BR', sex: 'female', ages: { min: 25, max: 40 }, seed: p.signature.seed });
});

Install

npm install @dasmig/persona

The package is an ES module only (no CommonJS build), for browsers, Web Workers and Node 20+.

It ships its own TypeScript types (index.d.ts) and the WebAssembly module (persona.wasm, about 8 MB, under 3 MB compressed), which bundlers such as Vite, webpack and esbuild pick up from new URL('persona.wasm', import.meta.url); pass locateFile or wasmBinary to createPersonaGenerator() to load it some other way. It has no dependencies.

Loading

createPersonaGenerator() instantiates the module and loads the data of all eight libraries. That takes a second or two (about 1.4 s on a desktop, more on a phone) and blocks the thread it runs on, and a generator uses about 90 MB of memory. So:

• Create one generator and reuse it. Each persona then takes about a third of a millisecond.
• In a browser, create it in a Web Worker so the page stays responsive, and post the personas (plain JSON) back:

// persona-worker.js, started with new Worker(new URL('./persona-worker.js', import.meta.url), { type: 'module' })
import { createPersonaGenerator } from '@dasmig/persona';

const ready = createPersonaGenerator();
onmessage = async ({ data: request }) => {
  const personas = await ready;
  try {
    postMessage({ persona: personas.generate(request) });
  } catch (error) {
    postMessage({ error: error.message });
  }
};

In a browser the module finds persona.wasm next to itself (new URL('persona.wasm', import.meta.url)). Vite and webpack 5 follow that and emit the file as an asset; webpack warns that it is over its recommended asset size, which is expected. To serve the file from elsewhere, pass Emscripten's locateFile, or pass its bytes as wasmBinary:

const personas = await createPersonaGenerator({ locateFile: file => '/assets/' + file });

In Node, the package's node export reads persona.wasm from disk.

persona.wasm is 8.3 MB, most of it data (city and name lists): 2.8 MB with gzip, 2.2 MB with brotli. Serve it compressed.

Request

Every field is optional. What is left out is drawn; what is given conditions the draws that depend on it. The country sets the city, the name culture, the body and the job; the age and sex set the rest.

• Countries. Only the countries in personas.countries have data in all eight libraries, so another code is an error rather than a persona with a name from the wrong culture.
• Traits. Fewer traits than asked are returned when no other trait is compatible with those already chosen (traits in one group exclude each other).
• Papers and wallet. Numbers, accounts and cards are test data. Without safe they are structurally valid and may match a real person's: never use them to identify anyone, to open accounts, to pass a check, or on a live payment system. See the limits.
• Family. relations: true adds relatives: the persona's parents, siblings, half-siblings, partners and children (up: 2 adds grandparents, down: 2 grandchildren), each with a name, birth date and, for the dead, a death date, linked by edges. members[0] is the persona. stepparents: true adds a parent's new partner (stepfather, stepmother, with a step_parent_of edge), the children the parent had with them (half-siblings) and their own children from before (stepsibling) and home: true adds household, who the persona lives with. Both are off by default. The family has its own seed stream, so the rest of the persona is identical with and without it.
• Home. home: true adds home (property-generator's dwelling type, tenure, rooms, floor area, year built and monthly_cost) and household_income, what everyone in the household earns. With relations, the home fits the family's household, which a home turns on; without, a household is drawn for the home alone. monthly_cost and household_income are null when nobody in the household earns.
• Dates. The generator never reads the clock. Pass referenceDate: new Date() for ages as of today, and keep the date with the seed if the persona must replay.
• Seeds. A seed is a 64-bit unsigned integer. A string is read as hexadecimal, optionally after 0x, which is the form of signature.seed: seed: '42' is 0x42 (66), not 42. Use a bigint or a hexadecimal string for seeds above Number.MAX_SAFE_INTEGER.

An invalid request throws before anything is generated: a TypeError for a field of the wrong type or an unknown field (a misspelt contry is an error, not a random country), and a RangeError for a value out of range. The message says which field and why. A failed call leaves the generator usable.

Result

generate() returns a Persona (see index.d.ts). It has name, sex, age, admin1 (the state or province) and signature, and each library's own result under country, city, birth, biodata, personality, interest and occupation. generateJson() returns the same as JSON text, exactly as the C++ library writes it.

Each part draws from its own random stream, split from the persona's seed. Forcing one choice does not shift the unrelated parts: the same seed with the other sex keeps the city and the personality.

Batches

For test data and populations, generate many personas from one batch seed:

// 10,000 personas, as objects or as JSON Lines (one persona per line).
const people = personas.generateBatch({ request: { country: 'BR' }, count: 10000, seed: 42 });
const lines = personas.generateBatchJsonl({ request: { country: 'BR' }, count: 10000, seed: 42 });

// The same personas, split across workers (Web Workers in a browser, worker threads in Node).
import { createPersonaPool } from '@dasmig/persona';
const pool = await createPersonaPool({ workers: 4 });
const same = await pool.generateBatchJsonl({ request: { country: 'BR' }, count: 10000, seed: 42 });
pool.close();

• Persona i of a batch is exactly generate({ ...request, seed }) for the seed derived from the batch seed and i (core::item_seed in the C++ libraries). So any persona replays on its own from its signature.seed, a range can be generated alone (first: 1000 starts at persona 1000), two batches that follow each other equal one, and the output is the same for any pool size.
• Options. request (the fields above except seed), count (0 to 2^31 - 1), seed (a random one if left out, which makes the batch unrepeatable) and first (default 0).
• Speed. About 14,000 personas per second on one generator in Node 24, 20,000 with a pool of 2 and 38,000 with a pool of 4, once the pool has started (about half a second). The JSON Lines form skips building the objects.
• Memory. Every worker loads its own module, about 60 MB, and a pool defaults to the number of cores, at most 4. The pool needs no SharedArrayBuffer, so it works on any page: pieces travel as strings.
• In a browser the pool starts module Web Workers from pool-worker.mjs next to the package's entry; bundlers that follow new URL(..., import.meta.url) pick it up.

Replaying personas

To recreate a persona later (for example, from a saved game), store its signature.seed and the request it was made with, including referenceDate.

The same seed and request give the same persona only with the same data. personas.dataHash identifies the data of all eight libraries, personas.identityDataHash id-generator's, personas.financeDataHash finance-generator's, personas.propertyDataHash and personas.relationshipDataHash the two a home adds, and personas.versions lists the library versions the module was built from. Store dataHash with the seed: if a package update changes it, the saved seed gives a different persona.

Each part of a persona also has a signature, with its own seed and its library's data hash.

Data

The data comes from open datasets (GeoNames, mledoze/countries, UN World Population Prospects, NCD-RisC, the CIA World Factbook, ILOSTAT and others) and from catalogues written for the libraries. DATA_LICENSES.txt lists each source and its licence. The names come from name-dataset; see name-generator's data notes for its provenance.

Each library documents its data's limits in its own doc/data.md.

Versions

The package version is its own. personas.versions lists the persona-generator release and the library releases this build was made from (for example persona-generator: 'v3.0.0'), and each package release is tagged package-v<version> in the repository, with the library versions it contains in its notes. The same seed gives the same persona only for the same library versions, so a library update that changes output is a major version of the package.

Source: persona-generator/package. Issues: github.com/dasmig/persona-generator/issues.

Licence

MIT for the code; see DATA_LICENSES.txt for the data.