{"id":29835932,"url":"https://github.com/kriasoft/codenames","last_synced_at":"2025-07-29T13:02:26.434Z","repository":{"id":306061035,"uuid":"1024859769","full_name":"kriasoft/codenames","owner":"kriasoft","description":"A tiny, zero-dependency library for generating memorable codenames from numbers.","archived":false,"fork":false,"pushed_at":"2025-07-23T11:19:11.000Z","size":69,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-23T13:20:31.012Z","etag":null,"topics":["bun","cli","codename","codenames","deployment-environment","deterministic","esm","generator","hash","human-readable","id-generator","identifier","javascript","memorable-id","name-generator","nodejs","preview-environment","typescript","zero-dependency"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kriasoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"koistya"}},"created_at":"2025-07-23T11:00:40.000Z","updated_at":"2025-07-23T11:18:48.000Z","dependencies_parsed_at":"2025-07-23T13:20:36.593Z","dependency_job_id":"a58512b9-56c3-403b-beb8-80f5cffce76e","html_url":"https://github.com/kriasoft/codenames","commit_stats":null,"previous_names":["kriasoft/codenames"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kriasoft/codenames","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kriasoft%2Fcodenames","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kriasoft%2Fcodenames/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kriasoft%2Fcodenames/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kriasoft%2Fcodenames/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kriasoft","download_url":"https://codeload.github.com/kriasoft/codenames/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kriasoft%2Fcodenames/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266701088,"owners_count":23970826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","cli","codename","codenames","deployment-environment","deterministic","esm","generator","hash","human-readable","id-generator","identifier","javascript","memorable-id","name-generator","nodejs","preview-environment","typescript","zero-dependency"],"created_at":"2025-07-29T13:01:02.654Z","updated_at":"2025-07-29T13:02:26.384Z","avatar_url":"https://github.com/kriasoft.png","language":"TypeScript","funding_links":["https://github.com/sponsors/koistya"],"categories":[],"sub_categories":[],"readme":"# Codenames\n\n[![npm version](https://badge.fury.io/js/codenames.svg)](https://badge.fury.io/js/codenames)\n[![npm downloads](https://img.shields.io/npm/dm/codenames.svg)](https://www.npmjs.com/package/codenames)\n[![bundle size](https://img.shields.io/bundlephobia/minzip/codenames)](https://bundlephobia.com/package/codenames)\n[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA lightweight TypeScript library that converts any number into consistent, memorable codename from a curated word list. It's designed for use cases where human-readability is more important than collision resistance, such as generating preview URLs or readable test IDs.\n\n```typescript\n// Default: uses the cities-20 word list\nimport codename from \"codenames\";\n\ncodename(1234); // \"london\"\ncodename(1234); // \"london\" (always the same)\ncodename(5678); // \"paris\"\ncodename(6789); // \"berlin\"\n\n// With custom words\ncodename(1234, [\"one\", \"two\", \"three\"]); // \"two\"\n```\n\n## Features\n\n- **🎯 Deterministic** - Same input always produces the same codename\n- **💬 Human-Readable** - Memorable names instead of random strings\n- **🚀 Zero Dependencies** - Lightweight and fast with no external packages\n- **⚡ Fast \u0026 Tiny** - 50,000+ generations per second, \u003c3KB core + ~2KB per theme\n- **🌐 Universal Runtime** - Works in Node.js, Bun, Deno, browsers, and edge runtimes\n- **🎨 Multiple Themes** - Cities, animals, colors, space, and more built-in themes\n- **🤖 CLI Included** - Generate codenames directly from your terminal\n\n## Use Cases\n\n### Preview Deployments\n\nManaging preview environments can get messy. You end up tracking which PR is deployed where, maintaining state, dealing with conflicts. Here's a simpler approach: use deterministic hashing to map PR numbers to memorable names.\n\n```typescript\nimport codename from \"codenames/cities-20\";\n\n// PR #1234 always maps to the same URL\nconst previewUrl = `https://${codename(1234)}.example.com`;\n// =\u003e https://london.example.com\n\n// PR #5678 gets a different one\nconst anotherUrl = `https://${codename(5678)}.example.com`;\n// =\u003e https://paris.example.com\n```\n\nWith 20 city names, you get 20 deployment slots. No database needed. The same PR number always produces the same city name, so URLs stay consistent throughout the PR lifecycle.\n\nPlus, it's easier to share \"london.example.com\" in Slack than \"preview-env-1234.k8s.us-east-1.example.com\".\n\n### Other Uses\n\n- **Docker Containers**: `docker run --name \"app-${codename(buildId)}\" myapp` → `app-tokyo`\n- **Session IDs**: `vienna-support` is friendlier than `sess_kJ8Hg2Bx9`\n- **Feature Flags**: `berlin-experiment` instead of `experiment_42`\n- **Test Data**: Generate predictable usernames (`cat`, `dog`, `bird`)\n\n## Getting Started\n\n```bash\nnpm install codenames\n```\n\n```typescript\n// Default: uses cities-20 word list\nimport codename from \"codenames\";\n// OR\nimport { codename } from \"codenames\";\n\nconst name = codename(1234); // \"london\"\n```\n\n### Using Different Themes\n\nYou can import specific themed word lists:\n\n```typescript\n// Import from a specific theme\nimport codename from \"codenames/animals-20\";\n// OR\nimport { codename } from \"codenames/animals-20\";\n\nconst name = codename(1234); // \"cat\"\n```\n\n### Using Custom Word Lists\n\nFor maximum flexibility, use the core function with your own words:\n\n```typescript\n// Use your own custom word list\nimport { codename } from \"codenames/core\";\n\nconst name = codename(1234, [\"alpha\", \"beta\", \"gamma\"]); // \"beta\"\n```\n\n## API Reference\n\n### Default API (with cities-20)\n\n```typescript\nimport codename from \"codenames\";             // default export\nimport { codename } from \"codenames\";         // named export\n\ncodename(input: number, words?: readonly string[]): string\n```\n\n- `input` - The number to convert\n- `words` - Optional array of words to use (defaults to cities-20)\n\n### Core API (with custom words)\n\n```typescript\nimport codename from \"codenames/core\";        // default export\nimport { codename } from \"codenames/core\";    // named export\n\ncodename(input: number, words: readonly string[]): string\n```\n\n- `input` - The number to convert\n- `words` - Required array of words to use\n\n### Themed APIs\n\n```typescript\nimport codename from \"codenames/cities-20\";   // default export\nimport { codename } from \"codenames/animals-50\"; // named export\n// ... and many more\n\ncodename(input: number): string\n```\n\nAll APIs support the same input types:\n\n- Positive integers: `123`, `1234`\n- Negative integers: `-42`\n- Decimals: `3.14` (converted to integers internally)\n- Large numbers: up to `Number.MAX_SAFE_INTEGER`\n\nSupported list sizes are 10, 20, 30, 50, and 100. The default theme uses 20 words.\n\n## Command Line Interface\n\nGenerate codenames directly from your terminal without writing any code.\n\n### Quick Start\n\n```bash\n# Generate a codename using the default cities-20 theme\nnpx codenames 1234\n# =\u003e london\n\n# Use the short alias\nnpx cn 1234\n# =\u003e london\n```\n\n### Installation (Optional)\n\nFor frequent use, install globally:\n\n```bash\nnpm install -g codenames\n# Now you can use it without npx\ncodenames 1234\n```\n\n### Options\n\n```bash\n# Choose a different theme\ncodenames 1234 --theme animals-50\n# =\u003e cat\n\n# Use short flag\ncodenames 1234 -t colors-10\n# =\u003e blue\n\n# Show help\ncodenames --help\n\n# Show version\ncodenames --version\n```\n\n### Examples\n\n```bash\n# Generate deployment URLs\necho \"Preview: https://$(codenames $PR_NUMBER).preview.example.com\"\n# =\u003e Preview: https://london.preview.example.com\n\n# Name Docker containers\ndocker run --name \"app-$(codenames $BUILD_ID)\" myapp:latest\n\n# Create test data\nfor i in {1..5}; do\n  echo \"User: $(codenames $i -t animals-20)\"\ndone\n# =\u003e User: cat\n# =\u003e User: dog\n# =\u003e User: bird\n# =\u003e User: fish\n# =\u003e User: cow\n```\n\n## Word Lists\n\nEach theme is available in multiple sizes: 10, 20, 30, 50, and 100 words. Choose based on your collision tolerance needs.\n\n- **[Adjectives](words/adjectives.txt)**: good, bad, big, small, new, old, hot, cold, fast, slow, ...\n- **[Animals](words/animals.txt)**: cat, dog, fish, bird, cow, pig, bee, ant, bat, fly, ...\n- **[Cities](words/cities.txt)**: paris, london, rome, tokyo, berlin, madrid, sydney, moscow, cairo, dubai, ...\n- **[Clothing](words/clothing.txt)**: shirt, jeans, shoe, hat, sock, dress, coat, belt, tie, pants, ...\n- **[Colors](words/colors.txt)**: red, blue, green, yellow, black, white, gray, pink, orange, purple, ...\n- **[Countries](words/countries.txt)**: china, japan, india, france, italy, spain, canada, mexico, brazil, germany, ...\n- **[Elements](words/elements.txt)**: gold, iron, lead, zinc, tin, copper, silver, carbon, oxygen, helium, ...\n- **[Emotions](words/emotions.txt)**: love, hate, joy, sad, fear, mad, happy, angry, glad, calm, ...\n- **[Food](words/food.txt)**: bread, milk, egg, rice, meat, fish, cake, apple, cheese, pasta, ...\n- **[Gems](words/gems.txt)**: ruby, pearl, jade, opal, amber, diamond, emerald, gold, silver, topaz, ...\n- **[Nature](words/nature.txt)**: tree, sun, sky, rain, moon, star, wind, sea, water, rock, ...\n- **[Snacks](words/snacks.txt)**: chips, nuts, cookie, pretzel, popcorn, candy, fruit, cheese, cracker, yogurt, ...\n\n## Contributing\n\nWe welcome contributions! Here's how to get started:\n\n### Development Setup\n\n```bash\ngit clone https://github.com/your-username/codenames.git\ncd codenames\nbun install\n```\n\n### Running Tests\n\n```bash\nbun test\n```\n\n### Building\n\n```bash\nbun run build\n```\n\n### Adding New Themes\n\nRun [`/generate-words \u003cname\u003e`](./.claude/commands/generate-words.md) AI prompt in Claude Code or a similar tool.\n\n### Pull Request Guidelines\n\n- Write clear commit messages\n- Add tests for new features\n- Update documentation as needed\n- Ensure all tests pass\n\n## Related Projects\n\n- **[React Starter Kit](https://github.com/kriasoft/react-starter-kit)** — Modern React starter kit with Bun, TypeScript, tRPC, and Cloudflare Workers.\n\n## Backers 💰\n\n\u003ca href=\"https://reactstarter.com/b/1\"\u003e\u003cimg src=\"https://reactstarter.com/b/1.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/2\"\u003e\u003cimg src=\"https://reactstarter.com/b/2.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/3\"\u003e\u003cimg src=\"https://reactstarter.com/b/3.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/4\"\u003e\u003cimg src=\"https://reactstarter.com/b/4.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/5\"\u003e\u003cimg src=\"https://reactstarter.com/b/5.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/6\"\u003e\u003cimg src=\"https://reactstarter.com/b/6.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/7\"\u003e\u003cimg src=\"https://reactstarter.com/b/7.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/8\"\u003e\u003cimg src=\"https://reactstarter.com/b/8.png\" height=\"60\" /\u003e\u003c/a\u003e\n\n## License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkriasoft%2Fcodenames","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkriasoft%2Fcodenames","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkriasoft%2Fcodenames/lists"}