Codenames

Codenames is a lightweight TypeScript library designed to transform any number into a memorable codename drawn from a curated list of words. It focuses on human-readable outputs instead of random strings, making it ideal for practical applications such as generating preview URLs or readable test identifiers.

Key Features

• Deterministic Output: The same input will always yield the same codename, ensuring consistency for tasks like URL generation.
• Human-Readable: Instead of unmemorable strings, the library offers distinct names that are easy to communicate.
• Zero Dependencies: Codenames is a lightweight solution that requires no external packages, optimizing performance.
• High Performance: Capable of generating over 50,000 codenames per second, with a minimal footprint of under 3KB for the core library and an additional ~2KB per theme.
• Universal Framework Support: Compatible across various environments including Node.js, Bun, Deno, browsers, and edge runtimes.
• Multiple Themes Available: Choose from a variety of built-in themes like cities, animals, colors, and more.
• Command Line Interface: Use the CLI to generate codenames directly from the terminal without needing to set up a separate script.

Use Cases

Codenames can streamline many processes, such as:

• Preview Deployments: Work with PR numbers seamlessly to create consistent deployment URLs, e.g., https://${codename(1234)}.example.com producing a friendly london.example.com.
• Naming Docker Containers: Generate more intuitive container names, e.g., app-${codename(buildId)} which results in more user-friendly identifiers like app-tokyo.
• Session Identifiers: Replace complex session IDs with memorable names like vienna-support.
• Feature Flags and Test Data: Use generated names in feature flags or to create predictable usernames.

Getting Started

To begin using Codenames, simply install the package and import it in your TypeScript project:

npm install codenames

Usage example:

import codename from "codenames";
const name = codename(1234);  // Example output: "london"

Flexibility with Themes

Codenames supports multiple themed word lists or even custom word arrays, accommodating various needs:

import { codename } from "codenames/animals-20";
const name = codename(1234); // Example output: "cat"

For maximum flexibility, custom word lists can be used:

import { codename } from "codenames/core";
const name = codename(1234, ["alpha", "beta", "gamma"]); // Example output: "beta"

Command Line Usage

To use Codenames via the command line, simply run:

npx codenames 1234

This generates the codename based on the default theme.

Codenames presents an effective solution for anyone needing to convert numbers into memorable, human-readable names quickly and efficiently.