unique-names-generator

unique-names-generator is a small TypeScript utility for producing human-readable, memorable name strings by combining words drawn from dictionaries — adjectives, animals, colors, countries, names, languages, and Star Wars characters ship built in, and any array of strings can be supplied as a custom dictionary. Names are assembled by picking one word per dictionary (up to a configurable length) and joining them with a separator, with three casing styles (lowerCase, upperCase, capital) and an optional NumberDictionary helper for appending random numeric suffixes.

Generation can be fully random (Math.random) or deterministic: passing a numeric or string seed drives an internal mulberry32 pseudo-random generator so the same seed always reproduces the same name, which is useful for testing or content that must be stable across runs. The library has zero runtime dependencies, ships CommonJS, ESM, and UMD builds via microbundle, and marks itself side-effect-free so bundlers can tree-shake unused dictionaries out of the final bundle.

What You Get

• uniqueNamesGenerator() - a single factory function that assembles a name string from an ordered array of dictionaries.
• Seven built-in dictionaries - adjectives, animals, colors, countries, languages, names, and Star Wars characters, each importable independently for tree-shaking.
• NumberDictionary helper - generates numeric-string arrays with a configurable min/max range or fixed digit length for numeric suffixes.
• Deterministic seeding - a numeric or string seed reproduces the exact same generated name every time via an internal mulberry32 PRNG.
• Full TypeScript typings - exported Config interface and typed dictionary exports, usable directly with no separate @types package.

Common Use Cases

• Anonymous session names - assign a friendly display name like red_clever_panda to a guest user or anonymous session.
• Test fixture data - generate readable placeholder names for seed data and fixtures in tests and demos.
• Docker/VM-style resource naming - produce human-memorable identifiers for containers, branches, or temporary resources.
• Reproducible demo content - use a fixed seed to generate the same sample names across CI runs or documentation screenshots.

Under The Hood

Architecture The public surface is a thin functional facade: uniqueNamesGenerator() in src/unique-names-generator.ts validates the caller-supplied config (throwing a descriptive error if dictionaries is missing) and delegates to the UniqueNamesGenerator class in src/unique-names-generator.constructor.ts, which owns all generation state behind private class fields (#dictionaries, #length, #separator, #style, #seed, #tmpSeed) and exposes a single generate() method that reduces over a slice of the dictionaries array, picking one word per dictionary via #getRandomFloat() and formatting it via #format(). Randomness itself is isolated in src/seed.ts, a standalone mulberry32 implementation the class falls back to only when a seed is provided (otherwise it uses Math.random()). Word lists live under src/dictionaries/ as independent modules re-exported from a single index.ts, keeping data cleanly separated from generation logic; changing the core class’s private state shape or the seed algorithm would only require touching this one file, since nothing else reaches into its internals.

Tech Stack Written entirely in TypeScript with zero runtime dependencies — every dependency in package.json is a devDependency. Builds are produced by microbundle, which emits CommonJS (dist/index.js), ESM (dist/index.m.js), and UMD (dist/index.umd.js) bundles plus .d.ts declarations from a single src/index.ts source entry, and the package sets sideEffects: false so consuming bundlers can tree-shake unused dictionary exports. Tests run under Jest with babel-jest (via @babel/preset-env and @babel/preset-typescript) rather than ts-jest, and np handles versioned releases.

Code Quality Three test files (unique-names-generator.test.ts, unique-names-generator.constructor.test.ts, seed.test.ts) plus a Jest snapshot file give reasonably thorough coverage: the main suite exercises separators, casing styles, custom and combined dictionaries, short-mode length, emoji separators, and the NumberDictionary helper, while seed.test.ts uses it.each over dozens of fixed seed/expected-index pairs to lock down PRNG determinism, and one case asserts the thrown error via toThrowErrorMatchingInlineSnapshot. Errors are explicit and descriptive (missing dictionaries, invalid length, length exceeding dictionary count) rather than swallowed. Naming is consistent camelCase with private-field (#) encapsulation, and ESLint (typescript-eslint) plus Prettier are configured for lint/format enforcement. CI is thin, though: the only GitHub Actions workflow present is CodeQL scanning, with test execution left to a stale Travis config (.travis.yml, Node 14) that Travis CI itself deprecated for open-source use — so it’s unclear tests are actually enforced on every push today.

What Makes It Unique Most random-name generators are purely non-deterministic; this one’s defining choice is a self-contained mulberry32 PRNG that’s reseeded on every generate() call, so supplying the same numeric or string seed always reproduces the identical name across runs and environments — useful for reproducible tests, fixtures, and demos without pulling in an external RNG dependency. Combined with per-dictionary tree-shaking and a same-shape custom-dictionary API (any string[] works exactly like a built-in one), the library stays a small, composable primitive rather than a batteries-included framework.