human-ids 1.0.14 → 2.0.0

package/dist/cjs/dictionaries/index.d.ts

@@ -0,0 +1,18 @@
+import type { Dictionary } from '../index';
+/**
+ * Built-in dictionaries indexed by language code.
+ * Currently supports 'en' (English) and 'es' (Spanish).
+ *
+ * @example
+ * ```typescript
+ * import { dictionaries } from 'human-ids';
+ *
+ * // Access English adjectives
+ * const englishAdjectives = dictionaries.en.adjectives;
+ *
+ * // Check available languages
+ * const languages = Object.keys(dictionaries); // ['en', 'es']
+ * ```
+ */
+declare const dictionaries: Record<string, Dictionary>;
+export { dictionaries };

package/dist/cjs/dictionaries/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dictionaries = void 0;
+const en_1 = require("./en");
+const es_1 = require("./es");
+/**
+ * Built-in dictionaries indexed by language code.
+ * Currently supports 'en' (English) and 'es' (Spanish).
+ *
+ * @example
+ * ```typescript
+ * import { dictionaries } from 'human-ids';
+ *
+ * // Access English adjectives
+ * const englishAdjectives = dictionaries.en.adjectives;
+ *
+ * // Check available languages
+ * const languages = Object.keys(dictionaries); // ['en', 'es']
+ * ```
+ */
+const dictionaries = {
+    en: en_1.en,
+    es: es_1.es,
+};
+exports.dictionaries = dictionaries;

package/dist/cjs/index.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Human IDs - A library to generate human-readable identifiers
+ * @packageDocumentation
+ * @module human-ids
+ */
+import { dictionaries } from './dictionaries';
+/**
+ * Dictionary containing word lists for ID generation.
+ * Each property maps word keys to their display values.
+ *
+ * @example
+ * ```typescript
+ * const customDictionary: Dictionary = {
+ *   adjectives: { happy: 'happy', bright: 'bright' },
+ *   colors: { red: 'red', blue: 'blue' },
+ *   nouns: { cat: 'cat', dog: 'dog' }
+ * };
+ * ```
+ */
+export interface Dictionary {
+    /** List of adjective words */
+    adjectives: string[];
+    /** List of color words */
+    colors: string[];
+    /** List of noun words */
+    nouns: string[];
+}
+/**
+ * Object containing the individual parts of a generated ID.
+ * Returned when `asObject: true` is set in the settings.
+ *
+ * @example
+ * ```typescript
+ * const parts: IdParts = {
+ *   adjective: 'happy',
+ *   color: 'blue',
+ *   noun: 'cat',
+ *   number1: '1234'
+ * };
+ * ```
+ */
+export interface IdParts {
+    /** The adjective component (if enabled) */
+    adjective?: string;
+    /** The color component (if enabled) */
+    color?: string;
+    /** The noun component (if enabled) */
+    noun?: string;
+    /** Additional properties for number components (number1, number2, etc.) */
+    [key: string]: string | undefined;
+}
+/**
+ * Configuration options for the number component(s) of generated IDs.
+ *
+ * @example
+ * ```typescript
+ * // Generate IDs with numbers between 1000-9999, zero-padded
+ * const numberSettings: NumberSettings = {
+ *   min: 1000,
+ *   max: 9999,
+ *   sets: 1,
+ *   completeWithZeros: true
+ * };
+ * ```
+ */
+export interface NumberSettings {
+    /**
+     * Minimum value for random numbers (inclusive)
+     * @default 0
+     */
+    min?: number;
+    /**
+     * Maximum value for random numbers (inclusive)
+     * @default 9999
+     */
+    max?: number;
+    /**
+     * Number of separate number components to include
+     * @default 1
+     * @example
+     * // With sets: 2, generates: "happy-blue-cat-1234-5678"
+     */
+    sets?: number;
+    /**
+     * Whether to pad numbers with leading zeros to match max length
+     * @default false
+     * @example
+     * // With max: 9999 and completeWithZeros: true
+     * // Number 42 becomes "0042"
+     */
+    completeWithZeros?: boolean;
+}
+/**
+ * Maps language codes to their component ordering.
+ * Defines the order in which ID parts appear for each language.
+ *
+ * @example
+ * ```typescript
+ * const semantics: SemanticsMap = {
+ *   en: ['adjective', 'color', 'noun', 'number'], // happy-blue-cat-123
+ *   es: ['noun', 'color', 'adjective', 'number']  // gato-azul-feliz-123
+ * };
+ * ```
+ */
+export interface SemanticsMap {
+    [lang: string]: Array<'noun' | 'adjective' | 'color' | 'number'>;
+}
+/**
+ * Configuration options for the ID generator.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with Spanish
+ * const settings: IdGeneratorSettings = {
+ *   lang: 'es',
+ *   separator: '_'
+ * };
+ *
+ * // Advanced usage with custom dictionary
+ * const advancedSettings: IdGeneratorSettings = {
+ *   lang: 'en',
+ *   adjective: true,
+ *   color: false,  // Exclude colors
+ *   noun: true,
+ *   number: { min: 100, max: 999 },
+ *   dictionary: {
+ *     adjectives: { cool: 'cool', awesome: 'awesome' }
+ *   }
+ * };
+ * ```
+ */
+export interface IdGeneratorSettings {
+    /**
+     * Language code for built-in dictionaries ('en' or 'es').
+     * Also accepts locale codes like 'en-US' (falls back to base language).
+     * @default 'en'
+     */
+    lang?: string;
+    /**
+     * Whether to include an adjective in the ID
+     * @default true
+     */
+    adjective?: boolean;
+    /**
+     * Whether to include a color in the ID
+     * @default true
+     */
+    color?: boolean;
+    /**
+     * Whether to include a noun in the ID
+     * @default true
+     */
+    noun?: boolean;
+    /**
+     * Whether to randomize the order of components
+     * @default false
+     */
+    randomOrder?: boolean;
+    /**
+     * Character(s) used to separate ID components
+     * @default '-'
+     */
+    separator?: string;
+    /**
+     * Return an object with individual parts instead of a string
+     * @default false
+     */
+    asObject?: boolean;
+    /**
+     * Custom component ordering per language.
+     * @default { en: ['adjective', 'color', 'noun', 'number'], es: ['noun', 'color', 'adjective', 'number'] }
+     */
+    semantics?: SemanticsMap;
+    /**
+     * Configuration for the number component(s)
+     * @default { min: 0, max: 9999, sets: 1, completeWithZeros: false }
+     */
+    number?: NumberSettings;
+    /**
+     * Custom dictionary to use (can partially override built-in words)
+     */
+    dictionary?: Partial<Dictionary>;
+}
+/**
+ * Generates a human-readable ID by combining adjectives, colors, nouns, and numbers.
+ *
+ * @param settings - Configuration options (with asObject: true)
+ * @returns Object containing individual ID components
+ *
+ * @example
+ * ```typescript
+ * // Get ID as object
+ * const parts = generateId({ asObject: true });
+ * // { adjective: 'happy', color: 'blue', noun: 'cat', number1: '1234' }
+ * ```
+ */
+declare function generateId(settings?: IdGeneratorSettings & {
+    asObject: true;
+}): IdParts;
+/**
+ * Generates a human-readable ID by combining adjectives, colors, nouns, and numbers.
+ *
+ * @param settings - Configuration options
+ * @returns Human-readable ID string
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - returns string like "happy-blue-cat-1234"
+ * const id = generateId();
+ *
+ * // Spanish language
+ * const spanishId = generateId({ lang: 'es' });
+ * // "gato-azul-feliz-5678"
+ *
+ * // Custom separator
+ * const underscoreId = generateId({ separator: '_' });
+ * // "happy_blue_cat_9012"
+ *
+ * // Without colors
+ * const noColorId = generateId({ color: false });
+ * // "happy-cat-3456"
+ *
+ * // Custom number range
+ * const customNumberId = generateId({
+ *   number: { min: 100, max: 999, completeWithZeros: true }
+ * });
+ * // "happy-blue-cat-042"
+ *
+ * // Multiple number sets
+ * const multiNumberId = generateId({ number: { sets: 2 } });
+ * // "happy-blue-cat-1234-5678"
+ *
+ * // Random component order
+ * const randomOrderId = generateId({ randomOrder: true });
+ * // "1234-cat-happy-blue" (random order each time)
+ *
+ * // Custom dictionary (partial override)
+ * const customId = generateId({
+ *   dictionary: {
+ *     adjectives: { cool: 'cool', awesome: 'awesome' }
+ *   }
+ * });
+ * ```
+ */
+declare function generateId(settings?: IdGeneratorSettings): string;
+export { generateId, dictionaries };

package/dist/cjs/index.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Human IDs - A library to generate human-readable identifiers
+ * @packageDocumentation
+ * @module human-ids
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dictionaries = void 0;
+exports.generateId = generateId;
+const dictionaries_1 = require("./dictionaries");
+Object.defineProperty(exports, "dictionaries", { enumerable: true, get: function () { return dictionaries_1.dictionaries; } });
+/**
+ * Default settings applied when options are not specified.
+ * @internal
+ */
+const defaultSettings = {
+    lang: 'en',
+    adjective: true,
+    color: true,
+    noun: true,
+    randomOrder: false,
+    separator: '-',
+    asObject: false,
+    semantics: {
+        es: ['noun', 'color', 'adjective', 'number'],
+        en: ['adjective', 'color', 'noun', 'number'],
+    },
+    number: {
+        min: 0,
+        max: 9999,
+        sets: 1,
+        completeWithZeros: false,
+    },
+};
+/**
+ * Generates a random integer between min and max (inclusive).
+ * @param min - Minimum value (inclusive)
+ * @param max - Maximum value (inclusive)
+ * @returns Random integer in the range [min, max]
+ * @internal
+ */
+function getRandomNumber(min, max) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+/**
+ * Picks a random element from an array.
+ * @param arr - Array to pick from
+ * @returns Random element from the array
+ * @internal
+ */
+function pickRandom(arr) {
+    return arr[Math.floor(Math.random() * arr.length)];
+}
+/**
+ * Resolves a language code to a supported language.
+ * Supports full locale codes (e.g., 'en-US' resolves to 'en').
+ * Falls back to 'en' if language is not supported.
+ * @param lang - Language code to resolve
+ * @returns Resolved language code ('en' or 'es')
+ * @internal
+ */
+function resolveLang(lang) {
+    if (dictionaries_1.dictionaries[lang])
+        return lang;
+    const base = lang.split('-')[0];
+    if (dictionaries_1.dictionaries[base])
+        return base;
+    return 'en';
+}
+function generateId(userSettings = {}) {
+    const settings = { ...defaultSettings, ...userSettings };
+    const lang = resolveLang(settings.lang);
+    const numberMin = settings.number && settings.number.min !== undefined ? settings.number.min : 0;
+    const numberMax = settings.number && settings.number.max !== undefined ? settings.number.max : 999;
+    const numberSets = (settings.number && settings.number.sets) || 1;
+    const completeWithZeros = (settings.number && settings.number.completeWithZeros) || false;
+    const customDict = settings.dictionary;
+    const builtinDict = dictionaries_1.dictionaries[lang];
+    const resolved = customDict
+        ? {
+            adjectives: customDict.adjectives ? [...new Set(customDict.adjectives)] : builtinDict.adjectives,
+            colors: customDict.colors ? [...new Set(customDict.colors)] : builtinDict.colors,
+            nouns: customDict.nouns ? [...new Set(customDict.nouns)] : builtinDict.nouns,
+        }
+        : builtinDict;
+    const parts = {};
+    if (settings.adjective) {
+        parts.adjective = pickRandom(resolved.adjectives);
+    }
+    if (settings.color) {
+        parts.color = pickRandom(resolved.colors);
+    }
+    if (settings.noun) {
+        parts.noun = pickRandom(resolved.nouns);
+    }
+    const maxNumberLength = completeWithZeros ? numberMax.toString().length : 0;
+    for (let i = 0; i < numberSets; i++) {
+        const num = getRandomNumber(numberMin, numberMax);
+        parts[`number${i + 1}`] = completeWithZeros
+            ? num.toString().padStart(maxNumberLength, '0')
+            : num.toString();
+    }
+    if (settings.randomOrder) {
+        const keys = Object.keys(parts);
+        const shuffledKeys = keys.sort(() => Math.random() - 0.5);
+        const shuffledParts = [];
+        for (const key of shuffledKeys) {
+            shuffledParts.push(parts[key]);
+        }
+        return shuffledParts.join(settings.separator);
+    }
+    if (settings.asObject) {
+        return parts;
+    }
+    const semantics = (settings.semantics && settings.semantics[lang]) || settings.semantics.en;
+    const result = semantics.map((key) => {
+        if (key !== 'number')
+            return parts[key];
+        // Collect all number parts directly instead of filtering with isNaN
+        const numberParts = [];
+        for (let i = 1; i <= numberSets; i++) {
+            numberParts.push(parts[`number${i}`]);
+        }
+        return numberParts.join('-');
+    });
+    return result.join(settings.separator);
+}

package/dist/esm/dictionaries/en.d.ts

@@ -0,0 +1,6 @@
+declare const words: {
+    adjectives: string[];
+    colors: string[];
+    nouns: string[];
+};
+export { words as en };