# 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.
[](https://www.npmjs.com/package/shortwords)
[](https://www.npmjs.com/package/shortwords)
[](https://opensource.org/licenses/MIT)
### Contents
- [Installation](#installation)
- [Usage](#usage)
- [API](#api)
- [CLI](#cli)
- [Reference](#reference)
### Installation
```bash
npm install shortwords
```
### Usage
Generate random 3-letter words.
```typescript
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.
```typescript
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.
```typescript
// 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.
```typescript
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.
```typescript
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.
```bash
# 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
```bash
# 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 `** - Set the number of words to generate (default: 10).
- **`-p, --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 |