memorable-ids
Version:
A flexible library for generating human-readable, memorable identifiers
238 lines (235 loc) • 6.97 kB
TypeScript
export { default as dictionary, dictionaryStats } from './dictionary.js';
/**
* Memorable ID Generator
*
* A flexible library for generating human-readable, memorable identifiers.
* Uses combinations of adjectives, nouns, verbs, adverbs, and prepositions
* with optional numeric/custom suffixes.
*
* @author Aris Ripandi
* @license MIT
*/
/**
* Type definition for suffix generator function
*/
type SuffixGenerator = () => string | null | undefined;
/**
* Configuration options for ID generation
*/
interface GenerateOptions {
/** Number of word components (1-5, default: 2) */
components?: number;
/** Suffix generator function (default: null) */
suffix?: SuffixGenerator | null;
/** Separator between parts (default: "-") */
separator?: string;
}
/**
* Parsed ID components structure
*/
interface ParsedId {
/** Array of word components */
components: string[];
/** Suffix part if detected, null otherwise */
suffix: string | null;
}
/**
* Collision scenario analysis
*/
interface CollisionScenario {
/** Number of IDs in scenario */
ids: number;
/** Collision probability (0-1) */
probability: number;
/** Formatted percentage string */
percentage: string;
}
/**
* Collision analysis result
*/
interface CollisionAnalysis {
/** Total possible combinations */
totalCombinations: number;
/** Array of collision scenarios */
scenarios: CollisionScenario[];
}
/**
* Generate a memorable ID
*
* @param options - Configuration options
* @returns Generated memorable ID
*
* @example
* ```typescript
* // Default: 2 components, no suffix
* generate() // "cute-rabbit"
*
* // 3 components
* generate({ components: 3 }) // "large-fox-swim"
*
* // With numeric suffix
* generate({
* components: 2,
* suffix: suffixGenerators.number
* }) // "quick-mouse-042"
*
* // Custom separator
* generate({
* components: 2,
* separator: "_"
* }) // "warm_duck"
* ```
*/
declare function generate(options?: GenerateOptions): string;
/**
* Default suffix generator - random 3-digit number
*
* @returns Random number suffix (000-999)
*
* @example
* ```typescript
* defaultSuffix() // "042"
* defaultSuffix() // "789"
* ```
*/
declare function defaultSuffix(): string;
/**
* Parse a memorable ID back to its components
*
* @param id - The memorable ID to parse
* @param separator - Separator used (default: "-")
* @returns Parsed components with structure
*
* @example
* ```typescript
* parse("cute-rabbit-042")
* // { components: ["cute", "rabbit"], suffix: "042" }
*
* parse("large-fox-swim")
* // { components: ["large", "fox", "swim"], suffix: null }
* ```
*/
declare function parse(id: string, separator?: string): ParsedId;
/**
* Calculate total possible combinations for given configuration
*
* @param components - Number of word components (1-5)
* @param suffixRange - Range of suffix values (default: 1 for no suffix)
* @returns Total possible unique combinations
*
* @example
* ```typescript
* calculateCombinations(2) // 5,304 (2 components, no suffix)
* calculateCombinations(2, 1000) // 5,304,000 (2 components + 3-digit suffix)
* calculateCombinations(3) // 212,160 (3 components, no suffix)
* ```
*/
declare function calculateCombinations(components?: number, suffixRange?: number): number;
/**
* Calculate collision probability using Birthday Paradox
*
* @param totalCombinations - Total possible combinations
* @param generatedIds - Number of IDs to generate
* @returns Collision probability (0-1)
*
* @example
* ```typescript
* // For 2 components (5,304 total), generating 100 IDs
* calculateCollisionProbability(5304, 100) // ~0.0093 (0.93%)
*
* // For 3 components (212,160 total), generating 10,000 IDs
* calculateCollisionProbability(212160, 10000) // ~0.00235 (0.235%)
* ```
*/
declare function calculateCollisionProbability(totalCombinations: number, generatedIds: number): number;
/**
* Get collision analysis for different ID generation scenarios
*
* @param components - Number of components
* @param suffixRange - Suffix range (1 for no suffix)
* @returns Analysis with total combinations and collision probabilities
*
* @example
* ```typescript
* getCollisionAnalysis(2)
* // {
* // totalCombinations: 5304,
* // scenarios: [
* // { ids: 100, probability: 0.0093, percentage: "0.93%" },
* // { ids: 500, probability: 0.218, percentage: "21.8%" },
* // ...
* // ]
* // }
* ```
*/
declare function getCollisionAnalysis(components?: number, suffixRange?: number): CollisionAnalysis;
/**
* Collection of predefined suffix generators
*/
declare const suffixGenerators: {
/**
* Random 3-digit number (000-999)
* Adds 1,000x multiplier to total combinations
*/
readonly number: typeof defaultSuffix;
/**
* Random 4-digit number (0000-9999)
* Adds 10,000x multiplier to total combinations
*/
readonly number4: () => string;
/**
* Random 2-digit hex (00-ff)
* Adds 256x multiplier to total combinations
*/
readonly hex: () => string;
/**
* Last 4 digits of current timestamp
* Adds ~10,000x multiplier (time-based, not truly random)
*/
readonly timestamp: () => string;
/**
* Random lowercase letter (a-z)
* Adds 26x multiplier to total combinations
*/
readonly letter: () => string;
};
/**
* Default export with all main functions
*/
declare const memorableId: {
readonly generate: typeof generate;
readonly parse: typeof parse;
readonly calculateCombinations: typeof calculateCombinations;
readonly calculateCollisionProbability: typeof calculateCollisionProbability;
readonly getCollisionAnalysis: typeof getCollisionAnalysis;
readonly suffixGenerators: {
/**
* Random 3-digit number (000-999)
* Adds 1,000x multiplier to total combinations
*/
readonly number: typeof defaultSuffix;
/**
* Random 4-digit number (0000-9999)
* Adds 10,000x multiplier to total combinations
*/
readonly number4: () => string;
/**
* Random 2-digit hex (00-ff)
* Adds 256x multiplier to total combinations
*/
readonly hex: () => string;
/**
* Last 4 digits of current timestamp
* Adds ~10,000x multiplier (time-based, not truly random)
*/
readonly timestamp: () => string;
/**
* Random lowercase letter (a-z)
* Adds 26x multiplier to total combinations
*/
readonly letter: () => string;
};
readonly defaultSuffix: typeof defaultSuffix;
};
export { calculateCollisionProbability, calculateCombinations, memorableId as default, defaultSuffix, generate, getCollisionAnalysis, parse, suffixGenerators };
export type { CollisionAnalysis, CollisionScenario, GenerateOptions, ParsedId, SuffixGenerator };