rword

A cryptographically secure Node.js random generator for real English words. Contains over 350,000 English words. Supports custom word lists and optional seeded generation.

Upgrading from V3? See the upgrade guide.

Note: Rword stores its words array in memory, and limited testing shows this to add about ~20-60 MB to Node's heap depending on which word list you choose. Rword is built to be fast and self-contained without the need for a database and this price is paid at the expense of your RAM.

npm install rword rword-english-recommended

Examples

Using the recommended (smaller) word list:

import { words } from 'rword-english-recommended';
import { Rword } from 'rword';

const rword = new Rword(words);
rword.generate(); // ['pocketful']
rword.generate(4); // ['disrupter', 'recognizes', 'unbuckle', 'responding']

Using the extended (bigger) word list:

import { words } from 'rword-english-extended';
import { Rword } from 'rword';

const rword = new Rword(words);
rword.generate();

Generate reproducible words from a custom seed:

const seedRword1 = new Rword(words, 'your_custom_seed_123');
seedRword1.generate(3); // ['abandon', 'gunpowder', 'pole']
const seedRword2 = new Rword(words, 'your_custom_seed_123');
seedRword2.generate(3); // ['abandon', 'gunpowder', 'pole']

Words

Rword offers two prebuilt English word lists you can install. Both contain only a-z characters. There are no numbers, symbols, spaces, or diacritics.

• rword-english-recommended
  • ~123k words
  • contains only words 3-10 characters long
  • size will possibly decrease in the future
• rword-english-extended
  • ~350k words
  • size will possibly increase in the future

Or, you can provide your own custom list as a string array or modify a prebuilt list. See below.

API

const rword = new Rword(words, seed)

Creates an instance of Rword with the specified word list and optional seed.

• words: string[] - The word list to load into the Rword instance.
• seed?: string - Optional - By providing a seed, you ensure that the sequence of random words generated by the instance is reproducible. This means that if you create two instances of Rword with the same word list and seed, they will generate the same sequence of words. This is not recommended unless you have a specific need for it.

rword.generate(length): string[]

Generates words from the instance's words array.

• length: number - Optional (default 1) - How many words to return

You may be tempted to use the shorthand new Rword('small').generate() as needed, but this is not recommended because creating an Rword instance causes the entire word list to be loaded and shuffled. It's recommended to keep and reuse as few instances as possible.

rword.shuffle(): void

Shuffles the instance's words array. This method is automatically called upon instantiation.

rword.getWords(): string[]

Returns the full (shuffled) words array used internally by the Rword instance.

rword.load(words): void

Loads a new array of words into the instance and shuffles it.

• words: string[] - The array of words to load into the instance.

V3 to V4 Migration Guide

• Imports:
  • Rword now exports an ES Module instead of CommonJS
  • Instead of importing a global rword instance, import the Rword class and then a separate word list like the rword-english-recommended package
• Instantiation: Create an instance of Rword with the desired word list and optional seed
• API Methods: The methods now belong to an instance and the options object is removed for filtering

Upgrade Steps

• Import:

  • V3

  import { rword } from 'rword';
  

  • V4

  import { words } from 'rword-english-recommended'; // or 'rword-english-extended'
  import { Rword } from 'rword'; // Capitalized export
  

• Create instance:

  • V3: Not needed
  • V4

  const rword = new Rword(words);
  

• Generate words:

  • V3

  // has filtering options
  // might return a string, or an array
  rword.generate(5, { length: '3-10', contains: /pattern/ });
  // has generateFromPool method for improved performance
  rword.generateFromPool(5);
  

  • V4

  // only the number of words is accepted
  // always returns an array
  // only has a single generate method
  rword.generate(5);
  

If you need the old filtering options, you should do this yourself on a words array and then load that new aray into an instance.