KeyFleur

Poetic API Key Generation for Modern Developers

generateKeyFleur({ mode: "celestial", theme: "sigil" })
// → "Nebula-847-Galaxy" ✨

📖 Documentation • 🎮 Try Online • 🐙 GitHub Issues

---

Why KeyFleur?

Stop generating API keys that look like someone smashed their keyboard. Create beautiful, human-readable identifiers that your team will actually remember.

😴 Traditional Keys kJ8#mP2qR9$vX7nL4wB6 aNm9Kp2QrX5vB8wL4jR7 7mK3$pQ9rN2xV8wL4jB6

✨ KeyFleur Keys Luna-Eclipse-Nocturnal Crystal-459-Amethyst Sage-7f2a

Features

🎨 Beautiful	🔧 Functional	🚀 Developer Experience
9 Generation Modes	Zero Dependencies	Full TypeScript Support
13 Themed Collections	URL-Safe Output	Comprehensive JSDoc
Human-Readable Keys	Pattern Validation	Modern ESM/CJS Support

🌈 Generation Modes

Choose from 9 different key generation patterns, each with its own aesthetic and use case.

🎭 Thematic Collections

From celestial space themes to steampunk mechanical vibes - 13 curated word collections.

🛡️ Production Ready

Zero dependencies, fully typed, tested, and ready for production use.

---

Quick Start

📦 Installation

# npm
npm install @usex/key-fleur

# yarn
yarn add @usex/key-fleur

# pnpm
pnpm add @usex/key-fleur

# bun
bun add @usex/key-fleur

Basic Usage

import { generateKeyFleur } from '@usex/key-fleur';

// One-liner for a beautiful key
const key = generateKeyFleur();
console.log(key); // "Nyrae-Soliv-Ethae"

Configuration

// Customize your keys
const apiKey = generateKeyFleur({ 
  mode: 'sigil',      // Key pattern
  theme: 'celestial'  // Word theme
});
// → "Nebula-742-Comet"

// Generate multiple keys
const sessionKeys = generateKeyFleur({ 
  count: 5, 
  theme: 'oceanic' 
});
// → ["Wave-Coral-Deep", "Tide-Gull-Salt", ...]

Validation

import { isValidKeyFleur } from '@usex/key-fleur';

const result = isValidKeyFleur("Crystal-459-Gem");
// → { valid: true, mode: "sigil", parts: ["Crystal", "459", "Gem"] }

🎮 Try it live • 📚 Full API docs

---

🎨 Generation Modes

🌸 haiku - Traditional 5-7-5 syllable poetry

generateKeyFleur({ mode: 'haiku', theme: 'nocturnal' })
// → "Luna-Eclipse-Void"

Perfect for: API keys, memorable identifiers

🔸 sigil - Word-number-word format

generateKeyFleur({ mode: 'sigil', theme: 'crystalline' })
// → "Crystal-459-Gem"

Perfect for: Session tokens, transaction IDs

🌱 seed - Compact word + hex

generateKeyFleur({ mode: 'seed', theme: 'forest' })
// → "Moss-4f2a"

Perfect for: Short codes, references

🪞 lace - Palindromic patterns

generateKeyFleur({ mode: 'lace', theme: 'oceanic' })
// → "wavefa-afevaw"

Perfect for: Artistic applications, unique IDs

🎭 All 9 Modes

Mode	Example	Best For
haiku	Luna-Eclipse-Void	API keys, memorable IDs
sigil	Crystal-459-Gem	Session tokens, transaction IDs
seed	Moss-4f2a	Short codes, references
lace	wavefa-afevaw	Artistic apps, unique IDs
sonnet	Rosefa-Lilyli	User handles, project names
rune	Oracle-Blade_dawn	Timestamped keys
mantra	Sand-Sand-Dune	Meditation apps, repeated actions
mirrora	af-fa	Minimal IDs, simple tokens
quartz	Gear45.45raeG	Complex keys, high entropy

🎭 Thematic Collections

13 carefully curated word collections to match your application's aesthetic

🌌 celestial nova, galaxy, nebula eclipse, stellar, cosmos 🌊 oceanic wave, coral, tide nautilus, reef, pearl 🌲 forest moss, grove, cedar glade, fern, birch 🔮 crystalline quartz, prism, facet amethyst, opal, gem

🦇 nocturnal luna, eclipse, shadow twilight, void, silence ☀️ sunny sol, gleam, radiant aurora, shine, gold 🌸 floreal rose, bloom, petal garden, lily, orchid ⚙️ steampunk gear, steam, valve chronometer, brass, cog

🐉 mythic oracle, phoenix, wyrm grimoire, titan, rune 🏜️ desert dune, mirage, ember sirocco, ash, mesa 📚 library scroll, codex, quill archive, tome, script 🕳️ decay rust, fracture, relic erosion, wear, time

// Mix and match themes with any mode
generateKeyFleur({ theme: 'celestial', mode: 'haiku' })
// → "Nova-Galaxy-Nebula"

generateKeyFleur({ theme: 'steampunk', mode: 'sigil' })  
// → "Gear-847-Steam"

API Reference

generateKeyFleur(options?)

Primary interface for generating KeyFleur keys.

generateKeyFleur(options?: {
  mode?: ModeKey;     // Generation mode (default: "haiku")
  theme?: ThemeKey;   // Theme collection (default: "haiku") 
  count?: number;     // Number of keys (default: 1, max: 100)
}): string | string[]

Examples:

generateKeyFleur();                              // Single haiku key
generateKeyFleur({ mode: 'sigil' });            // Single sigil key
generateKeyFleur({ theme: 'oceanic' });         // Ocean-themed haiku
generateKeyFleur({ count: 10 });                // Array of 10 keys
generateKeyFleur({ 
  mode: 'quartz', 
  theme: 'crystalline',
  count: 3 
});                                              // 3 crystal quartz keys

isValidKeyFleur(key, mode?)

Validates KeyFleur key patterns.

isValidKeyFleur(
  key: string,
  mode?: ModeKey
): {
  valid: boolean;
  mode?: ModeKey;
  reason?: string;
  parts?: string[];
}

Examples:

isValidKeyFleur("Luna-Eclipse-Void");
// { valid: true, mode: "haiku", parts: ["Luna", "Eclipse", "Void"] }

isValidKeyFleur("Crystal-459-Gem", "sigil");
// { valid: true, mode: "sigil", parts: ["Crystal", "459", "Gem"] }

isValidKeyFleur("invalid-key");
// { valid: false, reason: "Key does not match any known KeyFleur pattern" }

Legacy API

import { poeticKey } from '@usex/key-fleur';

// Original simple interface (still supported)
poeticKey(mode?: ModeKey, theme?: ThemeKey): string

Use Cases

🔐 Security & Authentication

• API keys that humans can actually read and remember
• Session tokens with aesthetic appeal
• Temporary access codes and passphrases
• OAuth state parameters
• CSRF tokens

🎮 Gaming & Creative

• Game save IDs and world seeds
• Character names and guild identifiers
• Creative project codenames
• Art piece references

📊 Business & Development

• Document and content identifiers
• Database record references
• Test data generation
• Demo and placeholder content
• Customer reference numbers

💼 Why Choose KeyFleur?

Traditional Random Keys:

kJ8#mP2qR9$vX7nL4wB6
aNm9Kp2QrX5vB8wL4jR7

KeyFleur Keys:

Luna-Eclipse-Nocturnal
Crystal-459-Amethyst

✅ Human-readable - Easy to communicate verbally
✅ Memorable - Natural language patterns stick in memory
✅ Beautiful - Aesthetically pleasing in UIs and logs
✅ Unique - Collision-resistant across themes and modes
✅ Functional - URL-safe, database-friendly, proper entropy

Advanced Usage & Customization

Batch Generation

import { generateKeyFleur, type ThemeKey, type ModeKey } from '@usex/key-fleur';

// Generate API keys for different environments
const keys = {
  development: generateKeyFleur({ theme: 'forest', count: 3 }),
  staging: generateKeyFleur({ theme: 'crystalline', count: 3 }),
  production: generateKeyFleur({ theme: 'celestial', count: 3 })
};

// Generate user session tokens
const sessionTokens = generateKeyFleur({ 
  mode: 'seed',
  theme: 'nocturnal',
  count: 50 
}) as string[];

Custom Validation

import { isValidKeyFleur } from '@usex/key-fleur';

function validateApiKey(key: string, expectedFormat: 'sigil' | 'seed') {
  const result = isValidKeyFleur(key, expectedFormat);
  
  if (!result.valid) {
    throw new Error(`Invalid API key format: ${result.reason}`);
  }
  
  return result;
}

// Use in your application
try {
  const validation = validateApiKey("Crystal-459-Gem", "sigil");
  console.log(`Valid ${validation.mode} key with parts:`, validation.parts);
} catch (error) {
  console.error(error.message);
}

Extending KeyFleur

import { THEMES, MODES, type ThemeKey } from '@usex/key-fleur';

// Add custom themes
const customThemes = {
  ...THEMES,
  cyberpunk: ['neon', 'grid', 'cyber', 'matrix', 'pulse', 'neural']
} as const;

// Create custom generator
function customKeyFleur(theme: keyof typeof customThemes = 'haiku') {
  const words = customThemes[theme];
  const selected = words[Math.floor(Math.random() * words.length)];
  return `${selected}-${Date.now().toString(36)}`;
}

Technical Details

Architecture

KeyFleur is built with a modular architecture:

• key-types.ts - TypeScript type definitions
• theme-data.ts - Curated word collections (13 themes × ~30 words each)
• string-utils.ts - Core utilities (syllable counting, random selection)
• generation-modes.ts - 9 different key generation algorithms
• index.ts - Main API with validation and error handling

Algorithms

• Syllable Estimation - Vowel-counting heuristics for haiku mode
• Pattern Generation - Deterministic transformations (reversals, mirroring)
• Random Selection - Cryptographically adequate randomness via Math.random()
• Validation - Regex-based pattern matching for all modes

Security Considerations

• ⚠️ Not cryptographically secure - Uses Math.random() for generation
• ✅ Adequate entropy - Large combination space across themes/modes
• ✅ URL-safe - No special characters that break URLs or JSON
• ✅ Collision-resistant - Very low probability of duplicates in practice

For cryptographic security, combine with additional entropy sources or use KeyFleur for non-security-critical identifiers.

Contributing

We welcome contributions! Here's how to get started:

Development Setup

git clone https://github.com/ali-master/key-fleur.git
cd key-fleur
npm install
npm run build
npm test

Adding New Themes

1. Add your theme to src/theme-data.ts
2. Update the ThemeKey type in src/key-types.ts
3. Add tests and documentation

Adding New Modes

1. Create your mode function in src/generation-modes.ts
2. Add it to the MODES export
3. Update the ModeKey type in src/key-types.ts
4. Add validation pattern to isValidKeyFleur

License

MIT © Ali Torki

---

_{Built with ❤️ by Ali Torki, developers who believe code can be beautiful}

⭐ Star us on GitHub • 🐦 Follow on Linkedin