{"id":30162967,"url":"https://github.com/ali-master/keyfleur","last_synced_at":"2025-08-11T17:48:58.266Z","repository":{"id":306499236,"uuid":"1026372079","full_name":"ali-master/keyfleur","owner":"ali-master","description":"Generate beautiful, memorable, and poetic API keys and unique identifiers for your applications.","archived":false,"fork":false,"pushed_at":"2025-07-25T22:03:49.000Z","size":444,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-26T03:44:58.830Z","etag":null,"topics":["api-key","id-generator","key-generator","poetic","unique-identifier"],"latest_commit_sha":null,"homepage":"https://keyfleur.usestrict.dev","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/ali-master.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","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}},"created_at":"2025-07-25T19:14:46.000Z","updated_at":"2025-07-25T22:15:26.000Z","dependencies_parsed_at":"2025-07-26T03:55:19.143Z","dependency_job_id":null,"html_url":"https://github.com/ali-master/keyfleur","commit_stats":null,"previous_names":["ali-master/keyfleur"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/ali-master/keyfleur","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ali-master%2Fkeyfleur","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ali-master%2Fkeyfleur/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ali-master%2Fkeyfleur/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ali-master%2Fkeyfleur/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ali-master","download_url":"https://codeload.github.com/ali-master/keyfleur/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ali-master%2Fkeyfleur/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269930263,"owners_count":24498686,"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-08-11T02:00:10.019Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","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":["api-key","id-generator","key-generator","poetic","unique-identifier"],"created_at":"2025-08-11T17:48:53.919Z","updated_at":"2025-08-11T17:48:58.256Z","avatar_url":"https://github.com/ali-master.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/logo.svg\" alt=\"KeyFleur Logo\" width=\"120\" height=\"120\" /\u003e\n\n# KeyFleur\n\n*Poetic API Key Generation for Modern Developers*\n\n[![npm version](https://img.shields.io/npm/v/@usex/key-fleur?style=flat-square\u0026color=007acc\u0026labelColor=000000)](https://npmjs.com/package/key-fleur)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-007acc?style=flat-square\u0026labelColor=000000)](https://www.typescriptlang.org/)\n[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success?style=flat-square\u0026labelColor=000000)](package.json)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square\u0026labelColor=000000)](LICENSE)\n[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@usex/key-fleur?style=flat-square\u0026color=success\u0026labelColor=000000)](https://bundlephobia.com/package/key-fleur)\n\n```typescript\ngenerateKeyFleur({ mode: \"celestial\", theme: \"sigil\" })\n// → \"Nebula-847-Galaxy\" ✨\n```\n\n**[📖 Documentation](#quick-start) • [🎮 Try Online](https://keyfleur.usestrict.dev) • [🐙 GitHub Issues](https://github.com/ali-master/key-fleur/issues)**\n\n\u003c/div\u003e\n\n---\n\n## Why KeyFleur?\n\nStop generating API keys that look like someone smashed their keyboard. Create beautiful, human-readable identifiers that your team will actually remember.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n**😴 Traditional Keys**\n```\nkJ8#mP2qR9$vX7nL4wB6\naNm9Kp2QrX5vB8wL4jR7\n7mK3$pQ9rN2xV8wL4jB6\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n**✨ KeyFleur Keys**\n```\nLuna-Eclipse-Nocturnal\nCrystal-459-Amethyst\nSage-7f2a\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## Features\n\n\u003cdiv align=\"center\"\u003e\n\n| 🎨 **Beautiful** | 🔧 **Functional** | 🚀 **Developer Experience** |\n|:---:|:---:|:---:|\n| 9 Generation Modes | Zero Dependencies | Full TypeScript Support |\n| 13 Themed Collections | URL-Safe Output | Comprehensive JSDoc |\n| Human-Readable Keys | Pattern Validation | Modern ESM/CJS Support |\n\n\u003c/div\u003e\n\n### 🌈 **Generation Modes**\nChoose from 9 different key generation patterns, each with its own aesthetic and use case.\n\n### 🎭 **Thematic Collections** \nFrom `celestial` space themes to `steampunk` mechanical vibes - 13 curated word collections.\n\n### 🛡️ **Production Ready**\nZero dependencies, fully typed, tested, and ready for production use.\n\n---\n\n## Quick Start\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📦 Installation\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# npm\nnpm install @usex/key-fleur\n\n# yarn\nyarn add @usex/key-fleur\n\n# pnpm\npnpm add @usex/key-fleur\n\n# bun\nbun add @usex/key-fleur\n```\n\n\u003c/details\u003e\n\n### Basic Usage\n\n```typescript\nimport { generateKeyFleur } from '@usex/key-fleur';\n\n// One-liner for a beautiful key\nconst key = generateKeyFleur();\nconsole.log(key); // \"Nyrae-Soliv-Ethae\"\n```\n\n### Configuration\n\n```typescript\n// Customize your keys\nconst apiKey = generateKeyFleur({ \n  mode: 'sigil',      // Key pattern\n  theme: 'celestial'  // Word theme\n});\n// → \"Nebula-742-Comet\"\n\n// Generate multiple keys\nconst sessionKeys = generateKeyFleur({ \n  count: 5, \n  theme: 'oceanic' \n});\n// → [\"Wave-Coral-Deep\", \"Tide-Gull-Salt\", ...]\n```\n\n### Validation\n\n```typescript\nimport { isValidKeyFleur } from '@usex/key-fleur';\n\nconst result = isValidKeyFleur(\"Crystal-459-Gem\");\n// → { valid: true, mode: \"sigil\", parts: [\"Crystal\", \"459\", \"Gem\"] }\n```\n\n\u003cdiv align=\"center\"\u003e\n\n**[🎮 Try it live](https://keyfleur.dev) • [📚 Full API docs](#api-reference)**\n\n\u003c/div\u003e\n\n---\n\n## 🎨 Generation Modes\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🌸 haiku\u003c/strong\u003e - Traditional 5-7-5 syllable poetry\u003c/summary\u003e\n\n```typescript\ngenerateKeyFleur({ mode: 'haiku', theme: 'nocturnal' })\n// → \"Luna-Eclipse-Void\"\n```\nPerfect for: API keys, memorable identifiers\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🔸 sigil\u003c/strong\u003e - Word-number-word format\u003c/summary\u003e\n\n```typescript\ngenerateKeyFleur({ mode: 'sigil', theme: 'crystalline' })\n// → \"Crystal-459-Gem\"\n```\nPerfect for: Session tokens, transaction IDs\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🌱 seed\u003c/strong\u003e - Compact word + hex\u003c/summary\u003e\n\n```typescript\ngenerateKeyFleur({ mode: 'seed', theme: 'forest' })\n// → \"Moss-4f2a\"\n```\nPerfect for: Short codes, references\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🪞 lace\u003c/strong\u003e - Palindromic patterns\u003c/summary\u003e\n\n```typescript\ngenerateKeyFleur({ mode: 'lace', theme: 'oceanic' })\n// → \"wavefa-afevaw\"\n```\nPerfect for: Artistic applications, unique IDs\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🎭 All 9 Modes\u003c/strong\u003e\u003c/summary\u003e\n\n| Mode | Example | Best For |\n|------|---------|----------|\n| `haiku` | `Luna-Eclipse-Void` | API keys, memorable IDs |\n| `sigil` | `Crystal-459-Gem` | Session tokens, transaction IDs |\n| `seed` | `Moss-4f2a` | Short codes, references |\n| `lace` | `wavefa-afevaw` | Artistic apps, unique IDs |\n| `sonnet` | `Rosefa-Lilyli` | User handles, project names |\n| `rune` | `Oracle-Blade_dawn` | Timestamped keys |\n| `mantra` | `Sand-Sand-Dune` | Meditation apps, repeated actions |\n| `mirrora` | `af-fa` | Minimal IDs, simple tokens |\n| `quartz` | `Gear45.45raeG` | Complex keys, high entropy |\n\n\u003c/details\u003e\n\n## 🎭 Thematic Collections\n\n\u003cdiv align=\"center\"\u003e\n\n*13 carefully curated word collections to match your application's aesthetic*\n\n\u003c/div\u003e\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n**🌌 celestial**\n```\nnova, galaxy, nebula\neclipse, stellar, cosmos\n```\n\n**🌊 oceanic** \n```\nwave, coral, tide\nnautilus, reef, pearl\n```\n\n**🌲 forest**\n```\nmoss, grove, cedar\nglade, fern, birch\n```\n\n**🔮 crystalline**\n```\nquartz, prism, facet\namethyst, opal, gem\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n**🦇 nocturnal**\n```\nluna, eclipse, shadow\ntwilight, void, silence\n```\n\n**☀️ sunny**\n```\nsol, gleam, radiant\naurora, shine, gold\n```\n\n**🌸 floreal**\n```\nrose, bloom, petal\ngarden, lily, orchid\n```\n\n**⚙️ steampunk**\n```\ngear, steam, valve\nchronometer, brass, cog\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n**🐉 mythic**\n```\noracle, phoenix, wyrm\ngrimoire, titan, rune\n```\n\n**🏜️ desert**\n```\ndune, mirage, ember\nsirocco, ash, mesa\n```\n\n**📚 library**\n```\nscroll, codex, quill\narchive, tome, script\n```\n\n**🕳️ decay**\n```\nrust, fracture, relic\nerosion, wear, time\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n```typescript\n// Mix and match themes with any mode\ngenerateKeyFleur({ theme: 'celestial', mode: 'haiku' })\n// → \"Nova-Galaxy-Nebula\"\n\ngenerateKeyFleur({ theme: 'steampunk', mode: 'sigil' })  \n// → \"Gear-847-Steam\"\n```\n\n## API Reference\n\n### `generateKeyFleur(options?)`\n\nPrimary interface for generating KeyFleur keys.\n\n```typescript\ngenerateKeyFleur(options?: {\n  mode?: ModeKey;     // Generation mode (default: \"haiku\")\n  theme?: ThemeKey;   // Theme collection (default: \"haiku\") \n  count?: number;     // Number of keys (default: 1, max: 100)\n}): string | string[]\n```\n\n**Examples:**\n```typescript\ngenerateKeyFleur();                              // Single haiku key\ngenerateKeyFleur({ mode: 'sigil' });            // Single sigil key\ngenerateKeyFleur({ theme: 'oceanic' });         // Ocean-themed haiku\ngenerateKeyFleur({ count: 10 });                // Array of 10 keys\ngenerateKeyFleur({ \n  mode: 'quartz', \n  theme: 'crystalline',\n  count: 3 \n});                                              // 3 crystal quartz keys\n```\n\n### `isValidKeyFleur(key, mode?)`\n\nValidates KeyFleur key patterns.\n\n```typescript\nisValidKeyFleur(\n  key: string,\n  mode?: ModeKey\n): {\n  valid: boolean;\n  mode?: ModeKey;\n  reason?: string;\n  parts?: string[];\n}\n```\n\n**Examples:**\n```typescript\nisValidKeyFleur(\"Luna-Eclipse-Void\");\n// { valid: true, mode: \"haiku\", parts: [\"Luna\", \"Eclipse\", \"Void\"] }\n\nisValidKeyFleur(\"Crystal-459-Gem\", \"sigil\");\n// { valid: true, mode: \"sigil\", parts: [\"Crystal\", \"459\", \"Gem\"] }\n\nisValidKeyFleur(\"invalid-key\");\n// { valid: false, reason: \"Key does not match any known KeyFleur pattern\" }\n```\n\n### Legacy API\n\n```typescript\nimport { poeticKey } from '@usex/key-fleur';\n\n// Original simple interface (still supported)\npoeticKey(mode?: ModeKey, theme?: ThemeKey): string\n```\n\n## Use Cases\n\n### 🔐 **Security \u0026 Authentication**\n- API keys that humans can actually read and remember\n- Session tokens with aesthetic appeal  \n- Temporary access codes and passphrases\n- OAuth state parameters\n- CSRF tokens\n\n### 🎮 **Gaming \u0026 Creative**\n- Game save IDs and world seeds\n- Character names and guild identifiers  \n- Creative project codenames\n- Art piece references\n\n### 📊 **Business \u0026 Development**\n- Document and content identifiers\n- Database record references\n- Test data generation\n- Demo and placeholder content\n- Customer reference numbers\n\n### 💼 **Why Choose KeyFleur?**\n\n**Traditional Random Keys:**\n```\nkJ8#mP2qR9$vX7nL4wB6\naNm9Kp2QrX5vB8wL4jR7\n```\n\n**KeyFleur Keys:**\n```\nLuna-Eclipse-Nocturnal\nCrystal-459-Amethyst\n```\n\n✅ **Human-readable** - Easy to communicate verbally  \n✅ **Memorable** - Natural language patterns stick in memory  \n✅ **Beautiful** - Aesthetically pleasing in UIs and logs  \n✅ **Unique** - Collision-resistant across themes and modes  \n✅ **Functional** - URL-safe, database-friendly, proper entropy\n\n## Advanced Usage \u0026 Customization\n\n### Batch Generation\n\n```typescript\nimport { generateKeyFleur, type ThemeKey, type ModeKey } from '@usex/key-fleur';\n\n// Generate API keys for different environments\nconst keys = {\n  development: generateKeyFleur({ theme: 'forest', count: 3 }),\n  staging: generateKeyFleur({ theme: 'crystalline', count: 3 }),\n  production: generateKeyFleur({ theme: 'celestial', count: 3 })\n};\n\n// Generate user session tokens\nconst sessionTokens = generateKeyFleur({ \n  mode: 'seed',\n  theme: 'nocturnal',\n  count: 50 \n}) as string[];\n```\n\n### Custom Validation\n\n```typescript\nimport { isValidKeyFleur } from '@usex/key-fleur';\n\nfunction validateApiKey(key: string, expectedFormat: 'sigil' | 'seed') {\n  const result = isValidKeyFleur(key, expectedFormat);\n  \n  if (!result.valid) {\n    throw new Error(`Invalid API key format: ${result.reason}`);\n  }\n  \n  return result;\n}\n\n// Use in your application\ntry {\n  const validation = validateApiKey(\"Crystal-459-Gem\", \"sigil\");\n  console.log(`Valid ${validation.mode} key with parts:`, validation.parts);\n} catch (error) {\n  console.error(error.message);\n}\n```\n\n### Extending KeyFleur\n\n```typescript\nimport { THEMES, MODES, type ThemeKey } from '@usex/key-fleur';\n\n// Add custom themes\nconst customThemes = {\n  ...THEMES,\n  cyberpunk: ['neon', 'grid', 'cyber', 'matrix', 'pulse', 'neural']\n} as const;\n\n// Create custom generator\nfunction customKeyFleur(theme: keyof typeof customThemes = 'haiku') {\n  const words = customThemes[theme];\n  const selected = words[Math.floor(Math.random() * words.length)];\n  return `${selected}-${Date.now().toString(36)}`;\n}\n```\n\n## Technical Details\n\n### Architecture\n\nKeyFleur is built with a modular architecture:\n\n- **`key-types.ts`** - TypeScript type definitions\n- **`theme-data.ts`** - Curated word collections (13 themes × ~30 words each)\n- **`string-utils.ts`** - Core utilities (syllable counting, random selection)\n- **`generation-modes.ts`** - 9 different key generation algorithms\n- **`index.ts`** - Main API with validation and error handling\n\n### Algorithms\n\n- **Syllable Estimation** - Vowel-counting heuristics for haiku mode\n- **Pattern Generation** - Deterministic transformations (reversals, mirroring)\n- **Random Selection** - Cryptographically adequate randomness via `Math.random()`\n- **Validation** - Regex-based pattern matching for all modes\n\n### Security Considerations\n\n- ⚠️ **Not cryptographically secure** - Uses `Math.random()` for generation\n- ✅ **Adequate entropy** - Large combination space across themes/modes  \n- ✅ **URL-safe** - No special characters that break URLs or JSON\n- ✅ **Collision-resistant** - Very low probability of duplicates in practice\n\nFor cryptographic security, combine with additional entropy sources or use KeyFleur for non-security-critical identifiers.\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/ali-master/key-fleur.git\ncd key-fleur\nnpm install\nnpm run build\nnpm test\n```\n\n### Adding New Themes\n\n1. Add your theme to `src/theme-data.ts`\n2. Update the `ThemeKey` type in `src/key-types.ts`\n3. Add tests and documentation\n\n### Adding New Modes\n\n1. Create your mode function in `src/generation-modes.ts`\n2. Add it to the `MODES` export\n3. Update the `ModeKey` type in `src/key-types.ts`\n4. Add validation pattern to `isValidKeyFleur`\n\n## License\n\nMIT © [Ali Torki](https://github.com/ali-master)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\n    \u003csub\u003eBuilt with ❤️ by \u003ca href=\"https://github.com/ali-master\" target=\"_blank\"\u003eAli Torki\u003c/a\u003e, developers who believe code can be beautiful\u003c/sub\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/ali-master/key-fleur\"\u003e⭐ Star us on GitHub\u003c/a\u003e •\n    \u003ca href=\"https://linkedin.com/in/alitorki\"\u003e🐦 Follow on Linkedin\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fali-master%2Fkeyfleur","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fali-master%2Fkeyfleur","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fali-master%2Fkeyfleur/lists"}