joyful

Generate friendly, safe-for-work word combinations for project names, usernames, labels, demo data, and unique-looking identifiers.

Quick Start

bun add joyful

import { joyful } from "joyful";

joyful(); // "amber-fox"
joyful({ segments: 3 }); // "golden-marble-cathedral"
joyful({ separator: "_" }); // "swift_otter"

You can also use the CLI:

joyful
joyful --segments 3
joyful --pattern color,nature,animal

Generate Names

By default, joyful() returns two lowercase words joined with -. The first word is a friendly prefix, either an adjective or a color. Later words come from the broader word lists.

import { joyful } from "joyful";

joyful(); // "bright-dolphin"
joyful({ segments: 4 }); // "kind-river-cello-baker"
joyful({ separator: "_" }); // "golden_panda"
joyful({ maxLength: 8 }); // "tan-elk"

maxLength filters word choices so the final string fits within the requested limit. If the limit is too short to produce a valid name, joyful() throws.

Pattern-Based Names

Use pattern when you want each word to come from a specific category.

joyful({ pattern: ["adjective", "animal"] }); // "happy-dolphin"
joyful({ pattern: ["color", "nature", "animal"] }); // "amber-river-otter"
joyful({ pattern: ["city", "nature", "space"] }); // "kyoto-river-orbit"

Pattern rules:

• Category names are singular, such as animal, color, city, and nature.
• The pattern length controls the number of words.
• pattern takes precedence over segments.
• separator and maxLength still apply to generated names.
• Unknown categories throw an error with the supported category names.

CLI

The CLI supports the same core generation options:

joyful
joyful --segments 3
joyful --separator _
joyful --max-length 12
joyful --pattern adjective,animal
joyful --pattern city,nature,space --separator _

Short flags are available for common generation options:

joyful -s 3
joyful -p _
joyful -m 12
joyful -t color,nature,animal

Count Permutations

Use permutations() to count possible unbounded combinations without generating a name.

import { permutations } from "joyful";

permutations(); // 997425
permutations({ segments: 3 }); // 2917468125
permutations({ pattern: ["adjective", "animal"] }); // 46081
permutations({ pattern: ["color", "nature", "animal"] }); // 4674684

The CLI can print the same counts:

joyful --permutations
joyful --permutations --segments 3
joyful --permutations --pattern color,nature,animal

For automation, add --json:

joyful --permutations --pattern color,nature,animal --json

{
  "pattern": ["color", "nature", "animal"],
  "permutations": 4674684
}

Permutation counts do not account for maxLength, because bounded generation depends on word lengths and fitting constraints.

API

joyful(options?)

Returns a generated name as a string.

| Option | Type | Default | Description | | ----------- | ------------------ | ------- | ------------------------------------- | | segments | number | 2 | Number of words to generate | | pattern | JoyfulCategory[] | none | Category pattern for each word | | separator | string | "-" | Character(s) between words | | maxLength | number | none | Maximum length of the returned string |

permutations(options?)

Returns the number of possible unbounded combinations as a number.

| Option | Type | Default | Description | | ---------- | ------------------ | ------- | ------------------------------ | | segments | number | 2 | Number of words to count | | pattern | JoyfulCategory[] | none | Category pattern for each word |

JoyfulCategory

Supported pattern categories:

type JoyfulCategory =
  | "adjective"
  | "animal"
  | "architecture"
  | "art"
  | "city"
  | "color"
  | "emotion"
  | "fashion"
  | "food"
  | "history"
  | "literature"
  | "music"
  | "mythology"
  | "nature"
  | "profession"
  | "science"
  | "space"
  | "sport"
  | "transportation";

Word Lists

All words are lowercase, single-token, safe-for-work terms.

| Category | Words | | -------------- | ----- | | Adjectives | 227 | | Animals | 203 | | Architecture | 184 | | Art | 186 | | Cities | 73 | | Colors | 114 | | Emotions | 89 | | Fashion | 169 | | Food | 186 | | History | 131 | | Literature | 197 | | Music | 162 | | Mythology | 164 | | Nature | 202 | | Professions | 288 | | Science | 223 | | Space | 131 | | Sports | 154 | | Transportation | 183 |

Default Permutations

Default generation starts with an adjective or color, then draws each later word from the non-prefix lists.

| Segments | Combinations | | -------- | ---------------------- | | 2 | 997,425 | | 3 | 2,917,468,125 | | 4 | 8,533,594,265,625 | | 5 | 24,960,763,226,953,124 |

Errors And Constraints

• segments must be at least 2.
• separator cannot be an empty string.
• maxLength must be a positive integer when provided.
• Unknown pattern categories throw an error.
• CLI --json is only supported with --permutations.
• CLI --permutations does not support --max-length.

SFW Guarantee

All word lists are manually curated to be safe for work and family-friendly. Every category has been audited to exclude profanity, slurs, and negative or distressing terms. You can use joyful-generated names in any context without worry.

Benchmarks

Run bun run perf to generate the runtime, startup, package size, and consumer bundle size report. See BENCHMARKS.md for what the report measures and how to interpret it.

Credits

Originally created by Hayden Bleasel.

Based on friendly-words by Glitch, with curated word lists and additional categories.

License

ISC