Shortwords

This library generates pronounceable 2, 3, and 4-letter English words. It is ideal for brainstorming unique project code names, creating short file extensions, or generating random identifiers.

Contents

• Installation
• Usage
• API
• CLI
• Reference

Installation

npm install shortwords

Usage

Generate random 3-letter words.

import shortwords from "shortwords";

const results = shortwords(3);
console.log([...results]);
// Example output (your results will vary):
[
  "fco", "adi", "apq", "imi",
  "aob", "ajy", "vzu", "rif"...
]

Apply constraints by chaining methods. Here we request exactly 5 words of size 4, following the CVCV pattern.

const results = shortwords(4).pattern('cvcv').results(5);

console.log([...results]);
// Example output (your results will vary):
['tucu', 'sivu', 'kive', 'rulu', 'gimu'];

// Get first word in list
console.log(results.get(0));
// output: tucu

Configure everything in one call using an options object.

// Configuration Signature:
shortwords(
  size,                 // integer (2, 3, or 4) for word length
  {
    results?: number,   // number of words to generate
    pattern?: string,   // syllable pattern string (e.g., "CVC", "VCV")
    lock?: boolean      // freeze the instance state
  }
)

// Single-call option:
const results = shortwords(3, { results: 8, pattern: "VCV" });

Use .mix() to ignore size boundaries and generate a random assortment of 2, 3, or 4-letter words.

const results = shortwords().mix().results(6);
// Mixed Size Words:
['veuq', 'iwdu', 'iof', 'qsi', 'oq', 'luiy'];

Lock a result to prevent further modifications. Attempts to change after .lock() are ignored.

const results = shortwords(3).results(3).lock();

results.pattern('vcv').results(10); // ignored

API

• .results(n) - Set the number of words to return. See below table for maximum counts.
• .pattern(str) - Enforce a syllable pattern (e.g., "cvc"). See below table for pattern.
• .get(index) - Retrieve a specific word from the result.
• .mix() - Ignore size limits and generate mixed 2, 3, and 4-letter words.
• .prev() - Retrieve the previous generated result.
• .history() - Retrieve all results generated during the current lifecycle.

CLI

This library includes a lightweight CLI for generating words directly from the terminal. Result is streams directly to standard output, it works perfectly with Unix pipes and file redirection.

# Generate default words (size 3, count 10)
npx shortwords

# Generate words of a specific size (2, 3, or 4)
npx shortwords 3

# Generate with a custom pattern and count
npx shortwords 4 -n 5 -p cvcv

# Generate a mixed assortment of lengths
npx shortwords --mix

# Overwrite a file with 20 generated words
npx shortwords 3 -n 20 > words.txt

# Append 5 new mixed words to an existing file
npx shortwords --mix -n 5 >> words.txt

# Pipe into Unix utilities (e.g., sort alphabetically)
npx shortwords 4 -n 50 | sort

# Pipe directly into a local LLM (like Ollama running Qwen)
 npx shortwords 3 -n 5 | ollama run qwen "Pick the best code name:"

Help

# View the general help menu and all available flags
npx shortwords --help

# View detailed help for a specific topic (e.g., pattern rules)
npx shortwords --help pattern

Flags

• -n, --results <number> - Set the number of words to generate (default: 10).
• -p, --pattern <pattern> - Enforce a specific syllable pattern (e.g., -p cvc).
• -m, --mix - Ignore size boundaries and generate mixed 2, 3, and 4-letter words.
• -h, --help [topic] - Display help information or details on a specific topic.
• -v, --version - Display the installed version of Shortwords.

Reference

Words are generated using strict Consonant (C) and Vowel (V) pools to ensure pronounceability.

| Character Type | Pool | Total | | ------------------ | ------------------------------------------------------------- | ----- | | Vowels (V) | a, e, i, o, u | 5 | | Consonants (C) | b, c, d, f, g, h, j, k, l, m, n, p, q, r, s, t, v, w, x, y, z | 21 |

| Size | Default Patterns | Result Example | Max Count | | ----- | ---------------------------------------------- | ---------------- | --------- | | 2 | CV, VC | to, up | 210 | | 3 | CVC, VCV, CVV, VVC, CCV, VCC | cat, ago, bee | 13,860 | | 4 | CVCV, VCVC, CVVC, VCCV, CCVV, VVCC, CCVC, CVCC | code, acid, book | 743,610 |