Usage

Analyzing a Single Username

import { analyzeUsername } from '@fazelstudio/username-intelligence';

const result = analyzeUsername('h4ck3r_man');

Options

You can pass an options object as the second argument:

const result = analyzeUsername('username', {
  strict: false,            // Enable stricter validation
  blockProfanity: false,    // Reject usernames containing profanity
  reservedWords: [],        // Custom blocked words
  checkVisual: true,        // Check for visual spoofing
  enableCache: true,        // Enable LRU result caching
  enableSecurity: true,     // Enable security analysis
  enableLinguistic: true,   // Enable linguistic analysis
  enableVisual: true,       // Enable visual analysis
  enablePatterns: true,     // Enable pattern detection
  enableStructure: true,    // Enable structural analysis
});

Output Structure

The result object contains:

Field	Description
input	Original input username
meta	Length, normalized form, byte/grapheme length
stats	Entropy, character counts
script	Unicode script detection, mixed-script flags
patterns	Detected patterns (leet, separator-style, etc.)
security	Threat detection (invisibles, homoglyphs, phishing)
structure	Structural analysis (transitions, density)
linguistic	Word-likeness, name-likeness, pronounceability
visual	Readability, aesthetic, distinctiveness scores
complexity	Charset size, efficiency
classification	Style, scores (0–100), levels, and recommendation

Scores and Levels

All scores are 0–100. Levels provide human-readable categories:

• overall: Combined quality score
• quality: Username quality
• security_risk: How risky the username appears (higher = riskier)
• suspicion: Suspicion level (higher = more suspicious)
• authenticity: How authentic the username seems
• professionalism: Professionalism score
• entropy: Shannon entropy value

Level examples: low, trusted, good, probably-authentic, semi-professional, recommended

Batch Analysis

Analyze multiple usernames at once:

import { batchAnalyze } from '@fazelstudio/username-intelligence';

const results = batchAnalyze(['h4ck3r_man', 'john_doe', 'user123'], {
  stopOnError: false,
  includeErrors: true,
});

Returns an array of { username, analysis, success } objects.

Comparing Usernames

import { compareUsernames } from '@fazelstudio/username-intelligence';

const comparison = compareUsernames('h4ck3r_man', 'hacker_man');
console.log(comparison.comparison.similarity_score);
// Output: e.g., 72 (out of 100)

Cache Management

import { clearCache, getCacheStats } from '@fazelstudio/username-intelligence';

console.log(getCacheStats());
// { size: 5, maxSize: 500 }

clearCache();

Utility Functions

import {
  normalizeUsername,
  calculateEntropy,
  detectHomoglyphs,
  detectConfusables,
  isLikelyPhishing,
  analyzeScriptConsistency,
} from '@fazelstudio/username-intelligence';

const normalized = normalizeUsername('MyUser_123');
const entropy = calculateEntropy('xcv892nm');
const hasHomoglyphs = detectHomoglyphs('раураl');
const isPhishing = isLikelyPhishing('раураl');

Error Handling

The library validates inputs before analysis:

analyzeUsername('');     // Throws: Username must be a non-empty string
analyzeUsername(123);    // Throws: Username must be a non-empty string
analyzeUsername('a'.repeat(1001)); // Throws: Username exceeds max length of 1000
batchAnalyze('string');  // Throws: batchAnalyze requires an array