@alistairheus/name-generator

Node library and CLI that generate first names from attributed regional lists (Ireland, Scotland, Norway, Sweden, Cologne/Germany, plus reconstructed Japan, France, Nordic, and ASOIAF tags).

This package is for Node 20+ (a worldbuilding server, scripts, CI). Do not import it from a React bundle: it reads JSON from disk.

Install

npm install @alistairheus/name-generator

Library

import { generateNames } from '@alistairheus/name-generator';

const names = generateNames({
  strategy: 'markov',
  gender: 'female',
  region: 'ireland',
  pool: 'exclusive',
  count: 10,
});

loadNameData() unions the regional JSON shipped in the package. It does not include the repo’s large unique dump (untagged sports-data names). --region any is the union of those regional lists.

--region selects a tag. --pool controls how strict that selection is:

| --pool | Meaning | | --- | --- | | register | Every name tagged with that region (default) | | exclusive | The name’s other tags stay inside a small overlap set (Ireland↔Scotland, Nordic cluster). Takeshi is not exclusive Japanese if it is also Swedish | | morph | Register names that pass European morph eligibility |

counts are source totals where the official file has them (Irish/Scottish births, Swedish bearers, Cologne births). They are not comparable across countries.

CLI

npx @alistairheus/name-generator --gender female --count 5
npx @alistairheus/name-generator --strategy markov --region ireland --pool exclusive --gender female --count 10

In this repo:

npm install
npm run generate -- --region ireland --pool exclusive --gender female --count 10

Options

| Option | Values | Default | Description | | --- | --- | --- | --- | | --strategy | random, morph, markov | random | How names are produced | | --gender | male, female, any | any | Which cleaned pool to use | | --region | any, ireland, scotland, norway, sweden, germany, japan, france, nordic, asoiaf | any | Keep names tagged with this region | | --pool | register, exclusive, morph | register | How strictly to filter that region | | --count | positive integer | 1 | How many unique names to print | | --json | flag | off | Print a JSON array instead of one name per line | | --help | flag | off | Show usage text |

Invalid options, a count larger than the random pool, or exhausted morph or markov retries print an error and exit with a nonzero status.

Strategies

random samples existing cleaned names uniformly, without replacement, using crypto.randomInt.

morph invents names from European given-name structure learned in the selected pool:

• it trains only on Latin given names with ordinary phonotactics and productive endings such as -ina, -elle, -ian, and -o
• it skips Japanese romanized morphemes, Arabic theophoric prefixes, and other shapes that do not follow that morphology
• it keeps stems that occur repeatedly, then joins stem + suffix only when the sound boundary is legal
• it does not generate hyphenated names

markov invents names from an order-3 letter chain trained uniformly, in memory, on the selected pool:

• each letter-only name in the pool contributes one set of letter triples; source counts are unused
• it skips hyphenated names and anything that is not a-z after accent folding
• it does not copy a training name
• --pool exclusive and --pool morph are the intended views; register still works and will learn the full tagged mix

Data

Official and reconstructed lists live in data/regions/. The unique JSON under data/unique/ is a local rebuild index for this repo and is not published.

Development

npm test
npm run typecheck
npm run build
npx tsx scripts/eval-markov.ts --region ireland --pool exclusive --gender female