random-words

random-words is a lightweight JavaScript library for generating random common English words, useful anywhere an application needs throwaway text — filling out mock blog posts, populating UI components with sample copy, seeding fixtures for automated tests, or generating a quick placeholder string without pulling in a full lorem-ipsum generator. It ships a single built-in word list alongside a small, flexible generate() function that can return one word, an exact or randomized count, results grouped into multi-word tokens, joined strings, or output run through a custom formatter — plus an optional seed for deterministic, reproducible output.

Originally maintained as its own npm package by the ApostropheCMS team, random-words has since been folded into their monorepo, but the last published version remains a small, dependency-light utility (its only runtime dependency is seedrandom, used for the optional seeded mode) that continues to see regular weekly downloads.

What You Get

• A built-in list of roughly 1,950 common English words, exported directly as wordList for use without going through the API.
• A generate() function that returns a single word by default, or an exact/random-range count of words as an array or joined string.
• Fine-grained control over output: minLength/maxLength word-size filters, wordsPerString grouping, a custom separator, and a formatter callback applied to each word.
• A seed option (backed by seedrandom) for deterministic output — the same seed always produces the same sequence of words.
• A count() helper that reports how many words in the list fall within a given length range, without generating any.
• Hand-written TypeScript declarations (index.d.ts) shipped alongside the JS source.

Common Use Cases

• Generating placeholder/sample text for mock blog posts, comments, or UI previews during development.
• Seeding test fixtures and factories with randomized-but-readable string data instead of Lorem Ipsum.
• Producing human-readable random identifiers or slugs (combined with a separator) for demo data.
• Load-testing or demoing text-heavy UI with reproducible content via the seeded mode.

Under The Hood

Architecture The module is a single flat file with no layering: a top-level exported wordList array (roughly 1,950 words) backs both exported functions. generate() normalizes its input (a bare number, an exactly count, or a min/max range) by mutating the caller-supplied options object in place, then drives a set of nested closures — word(), generateRandomWord(), limitWordSize(), and randInt() — to pick indices via either Math.random() or a seedrandom-seeded generator. count() is a stateless filter over the same wordList by length bounds. There’s no dependency injection and no data flow beyond a single call graph; the in-place mutation of the options argument is a minor code smell, and every consumer (generate, count, and the raw wordList export) depends directly on the shape of that one array.

Tech Stack Pure ESM JavaScript ("type": "module") with a single runtime dependency, seedrandom (^3.0.5), used only for the optional deterministic-seed mode. The lone devDependency is mocha (^10.2.0), run via npm test → mocha tests/test.js. Type information ships as a hand-written index.d.ts rather than being authored in TypeScript or generated from it. There’s no bundler or build step — main/types in package.json point straight at index.js/index.d.ts — and no CI configuration is present in the repository.

Code Quality tests/test.js uses Mocha with Node’s built-in assert.ok across roughly a dozen behavioral tests covering min/max ranges, exactly, minLength/maxLength, the various join values, and seeded reproducibility. The suite is legitimate but shallow — there’s no coverage combining formatter with separator, no tests for count() in isolation, and no negative/invalid-input tests (e.g. max < min). No linter or formatter configuration is present in the shallow clone, and error handling is essentially absent: malformed option shapes are not guarded against and will simply produce unexpected output rather than a clear error.

API Design The public surface is intentionally tiny — generate(count | options) and count(options) — with a single overloaded entry point covering count-only, min/max ranges, exact counts, joined-string output, per-string word grouping, custom formatting, and seeded determinism, all through one options bag, plus a zero-argument default that returns one word. The raw wordList is also exported directly so callers needing the underlying data don’t have to go through the API at all. The overload surface (return type varies between string and string[] depending on join/exactly) trades some type predictability for flexibility, and because index.d.ts is maintained by hand, its accuracy depends on manual upkeep rather than generation from source. Documentation is effectively gone — the current README is only a deprecation notice pointing at ApostropheCMS’s monorepo — so a new consumer has to read the source directly to learn the option set.