v1.1.0

🚀 Major Features

New Core API with Custom Word Lists

• New codenames/core module - Use your own custom word lists
• Flexible API - Support for both default cities-20 and custom arrays
• Better TypeScript support - Full type safety with generics

// New: Use custom word lists
import { codename } from "codenames/core";
codename(123, ["alpha", "beta", "gamma"]); // "beta"

// Enhanced: Default cities-20 with optional custom lists
import codename from "codenames";
codename(123); // "berlin" (from cities-20)
codename(123, ["custom", "words"]); // "words"

Comprehensive ESM Package Exports

• 77+ new export paths - Direct access to all themes and sizes
• Runtime-specific optimizations - Dedicated Bun and Deno entry points
• Tree-shaking friendly - Zero side effects for optimal bundling

// Direct theme imports
import codename from "codenames/animals-50";
import { codename } from "codenames/colors-100";

// All themes and sizes now available
import all from "codenames/all"; // Access to every word list

🧪 Testing & Quality

Extensive Test Coverage

• New test suites for all 12 themes across 5 size variants (60+ theme files)
• Core functionality testing with edge cases and error scenarios
• Integration tests for CLI and cross-module compatibility
• Word list validation ensuring consistency and quality

Enhanced Error Handling

• Robust input validation - Clear error messages for invalid inputs
• Finite number checks - Proper handling of NaN, Infinity, and edge cases
• Empty word list protection - Graceful failures with helpful messages

🛠️ Developer Experience

Improved CLI Interface

• Default theme support - No flags needed for basic usage
• Better error reporting - Clear, actionable error messages
• Enhanced theme selection - Support for all 12 themes and 5 sizes

# Simplified usage
codenames 1234              # Uses default cities-20
codenames 1234 --theme animals-50  # Specific theme and size

Enhanced Documentation

• Complete README rewrite - Detailed API documentation and examples
• Practical use cases - Real-world examples including preview deployments
• Blog content - Comprehensive guide for preview deployment workflows
• API references - JSDoc comments and TypeScript definitions

📦 Package & Distribution

Modern Package Structure

• ESM-first approach - Native ES modules with proper exports
• TypeScript declarations - Full type definitions for all exports
• Multi-runtime support - Optimized for Node.js, Bun, Deno, and browsers
• CLI binaries - Both codenames and cn command aliases

Enhanced Metadata

• Expanded keywords - Better discoverability on npm
• Proper licensing - SPDX headers on all source files
• Build improvements - Enhanced scripts and tooling

🎨 Word Lists & Themes

New Theme Management

• Consolidated word lists - New words/all.ts with complete collection
• Enhanced generation scripts - Better validation and consistency
• Improved distribution analysis - Hash distribution validation tools

All 12 Themes Available

Each theme now available in 5 sizes (10, 20, 30, 50, 100 words):

• Animals, Cities, Colors, Countries, Elements
• Emotions, Food, Gems, Nature, Snacks, Clothing, Adjectives

🔧 Technical Improvements

Code Architecture

• Factory pattern implementation - Clean, reusable codename generation
• Deterministic hashing - FNV-1a algorithm for consistent output
• Pure functions - Predictable, testable code architecture
• Modular design - Clear separation of concerns

Performance & Bundle Size

• Zero runtime dependencies - Lightweight, fast execution
• Optimized exports - Tree-shaking friendly for minimal bundles
• Efficient hashing - Sub-millisecond generation times

📋 Files Changed

77 files modified with 1,950 additions and 279 deletions:

New Files

• core/codename.ts - Core hashing and validation logic
• core/index.ts - Public core API
• core/index.test.ts - Core functionality tests
• words/all.ts - Complete word list collection
• words/all.test.ts - Comprehensive word list validation

Enhanced Files

• All 60+ theme files with improved exports and TypeScript types
• Complete README.md rewrite with practical examples
• Enhanced package.json with comprehensive exports
• Improved CLI with better UX and error handling
• Updated generation and analysis scripts

🎯 Breaking Changes

While this is a minor version bump, some import paths have changed:

Migration Guide

Before (v1.0.x):

import codename from "codenames/cities-20";

After (v1.1.0):

// Still works - backward compatible
import codename from "codenames/cities-20";

// New options available
import codename from "codenames"; // default cities-20
import { codename } from "codenames/core"; // custom words

The library maintains backward compatibility, but the new APIs provide more flexibility and better TypeScript support.

🚀 Getting Started

npm install [email protected]

// Quick start with default cities-20
import codename from "codenames";
console.log(codename(1234)); // "london"

// Use custom words
import { codename } from "codenames/core";
console.log(codename(1234, ["red", "green", "blue"])); // "green"

// Theme-specific imports
import animalName from "codenames/animals-50";
console.log(animalName(1234)); // "cat"

🔗 Resources

• GitHub: https://github.com/kriasoft/codenames
• npm Package: https://www.npmjs.com/package/codenames
• Pull Request: #1
• Documentation: See the enhanced README.md for complete API documentation

---

This release transforms codenames from a simple proof-of-concept into a production-ready library with comprehensive features, extensive testing, and excellent developer experience. Perfect for preview deployments, memorable identifiers, and any use case where you need deterministic, human-readable names.

v1.0.0

Release Notes - Codenames v1.0.0 🎉

Initial Release - Tired of staring at meaningless numbers? So were we. Codenames is a lightweight, zero-dependency library that turns pesky numbers into memorable, human-readable names.

We're excited to launch the first stable release of Codenames. It's a simple, performant library for generating unique deployment URLs, readable identifiers, and any other user-friendly reference you can dream up.

🚀 What is Codenames?

It turns this: 1234
Into this: "london"

import codename from "codenames/cities-20";

codename(1234); // "london"
codename(5678); // "paris"

Transform any number into a consistent, memorable name using curated word themes. It's perfect for:

• Preview Environments: PR 1234 → https://london.example.com
• Readable Identifiers: Database IDs, session tokens, deployment names.
• User-Friendly References: Meeting rooms, temporary resources, test data.

✨ Key Features

🎨 12 Curated Themes, 60 Variants

Why settle for one theme when you can have a dozen? From the majestic to the mundane, we've got you covered.

• Cities: paris, london, tokyo, rome, berlin, madrid, sydney, moscow...
• Animals: cat, dog, fish, bird, cow, pig, bee, ant, bat, fly...
• Colors: red, blue, green, yellow, black, white, gray, pink...
• Nature: tree, sun, sky, rain, moon, star, wind, sea...
• Food: bread, milk, egg, rice, meat, fish, cake, apple...
• Plus: Adjectives, Countries, Elements, Emotions, Gems, Clothing, and even Snacks!

Each theme is available in 5 sizes: 10, 20, 30, 50, and 100 words.

⚡ No Baggage, Runs Everywhere

• Pure TypeScript with absolutely no external dependencies.
• Universal compatibility: Works flawlessly in Node.js, Bun, Deno, and all modern browsers.
• ESM-first with comprehensive TypeScript support.
• Tree-shakable exports to keep your bundle size tiny.

🔐 Predictable & Reliable

• FNV-1a hashing algorithm ensures consistent, evenly-distributed results. No more "it worked on my machine" for your generated names.
• The same input always produces the same output—perfect for reproducible builds.
• Collision-resistant design suitable for production environments.
• Handles edge cases gracefully: negative numbers, decimals, and large values.

🖥️ A Handy Command Line Interface

# Install globally
npm install -g codenames

# Generate codenames
codenames 1234           # "moscow" (uses the default cities-20 theme)
cn 5678 -t animals       # "dog" (short alias for the win)
codenames 999 --theme colors --size 50  # "purple"

Features:

• Both codenames and cn command aliases.
• Theme and size selection via flags.
• Built-in help and real-world usage examples.
• Proper error handling and exit codes.

🧰 Flexible API Design

Theme-Specific Imports (The Simple Way):

import codename from "codenames/cities-20";
import animals from "codenames/animals-30";
import colors from "codenames/colors-10";

codename(1234); // "london"
animals(1234); // "pig"
colors(1234); // "red"

Bring Your Own Words:

import { createCodename } from "codenames";

const custom = createCodename(["alpha", "beta", "gamma"]);
custom(42); // "beta"

For the TypeScript Aficionados:

import { createTypedCodename } from "codenames/core";

const myCodename = createTypedCodename(["foo", "bar"] as const);
// Enjoy full TypeScript inference and autocomplete support.

📦 Package Details

• Size: < 10KB gzipped with the default theme.
• Exports: 74+ entry points covering all themes and sizes.
• TypeScript: Full type safety with .d.ts files included.
• Browser Support: All evergreen browsers (Chrome, Firefox, Safari, Edge).
• Node.js: Requires Node.js 18.0.0 or higher.

🧪 Quality & Testing

• 100% Test Coverage for core functionality.
• Comprehensive Test Suite that covers edge cases and error scenarios.
• Performance Benchmarks to validate hash distribution quality.
• Integration Tests to ensure everything plays nicely together.
• TypeScript Strict Mode with a zero any policy in our public API.

📊 Why FNV-1a for Hashing?

We did the math so you don't have to. After evaluating multiple hashing algorithms, we chose FNV-1a because it's the Goldilocks of hashing for this job:

• Excellent distribution quality across typical input ranges (like PR numbers 1000-9999).
• Wicked fast with minimal computational overhead.
• Collision-resistant enough for production use cases.
• Perfectly deterministic across all JavaScript runtimes.

🛠️ Development Experience

Modern Package Structure:

{
  "type": "module",
  "exports": {
    ".": "./dist/index.js",
    "./cities-20": "./dist/cities-20.js",
    "./animals-30": "./dist/animals-30.js"
    // ... and 70+ more exports
  }
}

Full TypeScript Support:

• Comprehensive type definitions.
• IntelliSense and autocomplete.
• Compile-time safety.
• Source maps for easier debugging.

🤝 Getting Started

// Basic usage
import codename from "codenames/cities-20";
console.log(codename(1234)); // "london"

// Try different themes
import animals from "codenames/animals-10";
import colors from "codenames/colors-30";

console.log(animals(1234)); // "dog"
console.log(colors(1234));  // "blue"

// CLI usage
npx codenames 1234 --theme nature --size 50

🗺️ What's Next?

This v1.0.0 release establishes a solid foundation. Future releases will focus on:

• More theme collections (we're open to suggestions!).
• Community-contributed wordlists.
• Advanced configuration options.
• Performance optimizations.
• Framework-specific integrations.

📝 License

MIT License - feel free to use this in your personal and commercial projects.

🙏 Acknowledgments

A huge thanks to the community for the early feedback and to the giants whose shoulders we stood on during our hash algorithm research. You made this deterministic, collision-resistant implementation possible.

---

Ready to transform your numbers into memorable names?

npm install codenames

Happy coding! 🚀