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

# 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

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

Perfect for: API keys, memorable identifiers

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

Perfect for: Session tokens, transaction IDs

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

Perfect for: Short codes, references

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

Perfect for: Artistic applications, unique IDs

| 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