human-ids 1.0.14 → 1.2.0

package/dist/dictionaries/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Dictionary management module for human-ids.
+ * Handles built-in dictionaries and caching of resolved word arrays.
+ * @module dictionaries
+ * @internal
+ */
+import type { Dictionary } from '../index';
+/**
+ * Dictionary with word lists converted to arrays for efficient random selection.
+ * @internal
+ */
+export interface ResolvedDictionary {
+    /** Array of adjective words */
+    adjectives: string[];
+    /** Array of color words */
+    colors: string[];
+    /** Array of noun words */
+    nouns: string[];
+}
+/**
+ * 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 = Object.keys(dictionaries.en.adjectives);
+ *
+ * // Check available languages
+ * const languages = Object.keys(dictionaries); // ['en', 'es']
+ * ```
+ */
+declare const dictionaries: Record<string, Dictionary>;
+/**
+ * Converts a Dictionary (with Record objects) to a ResolvedDictionary (with arrays).
+ * Results are cached for performance.
+ *
+ * @param dict - Dictionary to resolve
+ * @returns Dictionary with word lists as arrays
+ * @internal
+ */
+declare function resolveDictionary(dict: Dictionary): ResolvedDictionary;
+export { dictionaries, resolveDictionary };

package/dist/dictionaries/index.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Dictionary management module for human-ids.
+ * Handles built-in dictionaries and caching of resolved word arrays.
+ * @module dictionaries
+ * @internal
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dictionaries = void 0;
+exports.resolveDictionary = resolveDictionary;
+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 = Object.keys(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;
+/**
+ * Cache for resolved dictionaries to avoid repeated Object.values() calls.
+ * @internal
+ */
+const resolvedCache = new Map();
+/**
+ * Converts a Dictionary (with Record objects) to a ResolvedDictionary (with arrays).
+ * Results are cached for performance.
+ *
+ * @param dict - Dictionary to resolve
+ * @returns Dictionary with word lists as arrays
+ * @internal
+ */
+function resolveDictionary(dict) {
+    let resolved = resolvedCache.get(dict);
+    if (!resolved) {
+        resolved = {
+            adjectives: Object.values(dict.adjectives),
+            colors: Object.values(dict.colors),
+            nouns: Object.values(dict.nouns),
+        };
+        resolvedCache.set(dict, resolved);
+    }
+    return resolved;
+}

package/dist/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 {
+    /** Map of adjective keys to their display values */
+    adjectives: Record<string, string>;
+    /** Map of color keys to their display values */
+    colors: Record<string, string>;
+    /** Map of noun keys to their display values */
+    nouns: Record<string, 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/index.js

@@ -0,0 +1,135 @@
+"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 = {}) {
+    var _a, _b, _c;
+    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;
+    // Resolve dictionary arrays (cached for built-in dictionaries)
+    const customDict = settings.dictionary;
+    const builtinDict = dictionaries_1.dictionaries[lang];
+    const resolved = (0, dictionaries_1.resolveDictionary)(customDict
+        ? {
+            adjectives: (_a = customDict.adjectives) !== null && _a !== void 0 ? _a : builtinDict.adjectives,
+            colors: (_b = customDict.colors) !== null && _b !== void 0 ? _b : builtinDict.colors,
+            nouns: (_c = customDict.nouns) !== null && _c !== void 0 ? _c : 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);
+}
+// CJS backwards compatibility
+// Allows: const generateId = require('human-ids')
+// And:    const { generateId, dictionaries } = require('human-ids')
+module.exports = generateId;
+module.exports.generateId = generateId;
+module.exports.dictionaries = dictionaries_1.dictionaries;

package/package.json

@@ -1,28 +1,55 @@
 {
   "name": "human-ids",
-  "version": "1.0.14",
-  "description": "A library to generate human readable IDs",
-  "main": "index.js",
+  "version": "1.2.0",
+  "description": "A zero-dependency TypeScript library to generate human-readable IDs. Supports English and Spanish with ~209 billion unique combinations.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
     "test": "jest --reporters=default --reporters=jest-html-reporter"
   },
   "keywords": [
-    "readable",
+    "human-readable",
+    "id",
     "ids",
-    "humans",
-    "for-humans",
+    "identifier",
+    "generator",
+    "unique",
+    "uuid-alternative",
+    "readable-id",
+    "friendly-id",
     "human-ids",
-    "simple",
-    "simple-ids"
+    "typescript",
+    "english",
+    "spanish",
+    "i18n"
   ],
   "author": "JC Mujica",
   "license": "ISC",
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "jest": "^29.6.1",
-    "jest-html-reporter": "^3.10.1"
+    "jest-html-reporter": "^3.10.1",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/jcmujica/human-ids"
+    "url": "git+https://github.com/jcmujica/human-ids.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jcmujica/human-ids/issues"
+  },
+  "homepage": "https://github.com/jcmujica/human-ids#readme",
+  "engines": {
+    "node": ">=14.0.0"
   }
-}
+}

package/CHANGELOG.md

@@ -1,72 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-## [Unreleased]
-
-## [1.0.14] - 2023-07-19
-
-### Added
-- Added semantics support to be passed as user settings to oder words according to the language
-- Added default semantics for english and spanish languages
-
-## [1.0.13] - 2023-07-10
-
-### Added
-- Added asObject setting to return an object with the words
-## [1.0.12] - 2023-07-07
-
-### Fixed
-- Fixed bug with undefined disctionaries
-## [1.0.11] - 2023-07-07
-
-### Fixed
-- Fixed bug with custom dictionaries
-## [1.0.10] - 2023-07-07
-
-### Added
-- Added separator customization
-- Added random ordering for segments
-- Added support for custom dictionary
-## [1.0.9] - 2023-07-07
-
-### Changed
-- Changed removed init console.log
-## [1.0.8] - 2023-07-07
-
-### Changed
-- Changed README.md to correctly display usage information
-## [1.0.7] - 2023-07-07
-
-### Changed
-- Changed README.md to correctly display usage information
-## [1.0.6] - 2023-07-07
-
-### Changed
-- Changed README.md to correctly display usage information
-## [1.0.5] - 2023-07-07
-
-### Remove
-- Removed tests file
-## [1.0.4] - 2023-07-07
-
-### Fixed
-- Fixed module definition
-## [1.0.3] - 2023-07-07
-
-### Added
-- Added default settings
-## [1.0.2] - 2023-07-07
-
-### Changed
-- Refactor into function
-## [1.0.1] - 2023-07-07
-
-### Added
-- Added Changelog
-- Added gitignore and git link in package.json
-
-## [1.0.0] - 2023-07-07
-
-### Added
-- A library to generate human-readable IDs.