human-ids 1.0.12 → 1.0.14

package/CHANGELOG.md

@@ -4,6 +4,16 @@ 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

package/README.md

@@ -55,6 +55,13 @@ const settings = {
   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: 999,
@@ -70,18 +77,51 @@ console.log(humanId())
 
 The settings object allows you to customize the ID generation process. The available options are:
 
-    lang: The language of the generated words (e.g., 'en' for English, 'es' for Spanish).
-    adjective: Set to true to include an adjective in the ID (default: false).
-    color: Set to true to include a color in the ID (default: false).
-    noun: Set to true to include a noun in the ID (default: false).
-    randomOrder: Set to true to include a random order in the ID segments (default: false).
-    separator: Set to true to change a separator in the ID
-    number: An object that configures the number part of the ID:
-        min: The minimum value of the number (default: 0).
-        max: The maximum value of the number (default: 999).
-        completeWithZeros: Set to true to pad the number with leading zeros (default: false).
-        sets: The number of sets of random numbers to include, separated by a hyphen (-) (default: 1).
+    userSettings (optional): An object containing various options to customize the generated ID. It includes the following properties:
+        lang (string): The language for the ID generation. You can specify the language code (e.g., 'en' for English, 'es' for Spanish).
+        adjective (boolean): Include an adjective component in the generated ID. (Default: true)
+        color (boolean): Include a color component in the generated ID. (Default: true)
+        noun (boolean): Include a noun component in the generated ID. (Default: true)
+        randomOrder (boolean): Randomize the order of ID components. (Default: false)
+        separator (string): The separator used to join the ID components. (Default: '-')
+        asObject (boolean): Return the ID as an object instead of a string. (Default: false)
+        semantics (object|null): An object specifying the order of components based on language. For example, you can set the order for Spanish using "es": ['noun', 'color', 'adjective', 'number'].
+        number (object): An object containing settings for the number component:
+            min (number): The minimum value for the number component. (Default: 0)
+            max (number): The maximum value for the number component. (Default: 999)
+            completeWithZeros (boolean): Pad the number with leading zeros to match the maximum length. (Default: false)
+        dictionary (object): An object containing custom dictionaries for adjectives, colors, and nouns:
+            adjectives (object): A dictionary of adjectives for different languages.
+            colors (object): A dictionary of colors for different languages.
+            nouns (object): A dictionary of nouns for different languages.
+
+## Return Value
+The generateId function returns a unique identifier as a string by default. If the asObject option is set to true, the function returns an object containing the individual components of the ID.
+
+## Examples
+
+### Generate an ID with default settings:
+
+```javascript
+
+const id = generateId({ lang: 'en' });
+console.log(id); // Example output: "green-house-123"
+```
+
+### Generate an ID as an object:
 
+```javascript
+
+const idObject = generateId({ lang: 'es', asObject: true });
+console.log(idObject);
+// Example output:
+// {
+//   adjective: 'casa',
+//   color: 'verde',
+//   noun: 'montaña',
+//   number: '0123'
+// }
+```
 ## Test Results
 
 While the generated IDs strive for uniqueness, it's important to note that absolute uniqueness cannot be guaranteed, especially with a finite set of words and numbers. During the uniqueness test, the generator produced 999,722 unique IDs out of the expected 1,000,000. This means that a small number of duplicates may occur in practice.
@@ -89,4 +129,11 @@ License
 
 This project is licensed under the ISC License.
 
-Feel free to modify the `README.md` file to fit your project's specific details and requirements.
+Feel free to modify the `README.md` file to fit your project's specific details and requirements.
+
+## Contributing
+
+Contributions and bug reports are welcome! Feel free to open an issue or submit a pull request on the GitHub repository. Please ensure that your code follows the project's coding standards and includes appropriate test coverage.
+## License
+
+This project is licensed under the MIT License.

package/index.d.ts

@@ -6,6 +6,10 @@ declare module 'human-ids' {
     noun?: boolean;
     randomOrder?: boolean;
     separator?: string;
+    asObject?: boolean;
+    semantics?: {
+      [key: string]: string['noun' | 'adjective' | 'color' | 'number'];
+    } | null;
     number?: {
       min?: number;
       max?: number;

package/index.js

@@ -1,12 +1,17 @@
 const dictionaries = require('./dictionaries');
 
 const defaultSettings = {
-  lang: 'es',
+  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: 999,
@@ -16,15 +21,22 @@ const defaultSettings = {
 };
 
 function generateId(userSettings = {}) {
-  const settings = {...defaultSettings, ...userSettings};
-  const lang = dictionaries[settings.lang] ? settings.lang : dictionaries[settings.lang?.split('-')[0]] ? settings.lang?.split('-')[0] : 'en';
+  const settings = { ...defaultSettings, ...userSettings };
+  const lang = dictionaries[settings.lang]
+    ? settings.lang
+    : dictionaries[settings.lang?.split('-')[0]]
+    ? settings.lang?.split('-')[0]
+    : 'en';
   const useAdjective = settings.adjective || false;
   const useColor = settings.color || false;
   const useNoun = settings.noun || false;
-  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 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 completeWithZeros =
+    settings.number && settings.number.completeWithZeros || false;
 
   function getRandomNumber(min, max) {
     return Math.floor(Math.random() * (max - min + 1)) + min;
@@ -40,48 +52,72 @@ function generateId(userSettings = {}) {
   }
 
   function getAdjectives() {
-    return settings.dictionary && settings.dictionary.adjectives ? settings.dictionary.adjectives : dictionaries[lang].adjectives;
+    return settings.dictionary && settings.dictionary.adjectives
+      ? settings.dictionary.adjectives
+      : dictionaries[lang].adjectives;
   }
 
   function getColors() {
-    return settings.dictionary && settings.dictionary.colors ? settings.dictionary.colors : dictionaries[lang].colors;
+    return settings.dictionary && settings.dictionary.colors
+      ? settings.dictionary.colors
+      : dictionaries[lang].colors;
   }
 
   function getNouns() {
-    return settings.dictionary && settings.dictionary.nouns ? settings.dictionary.nouns : dictionaries[lang].nouns;
+    return settings.dictionary && settings.dictionary.nouns
+      ? settings.dictionary.nouns
+      : dictionaries[lang].nouns;
   }
 
-  const parts = [];
+  const parts = {};
 
   if (useAdjective) {
     const adjectives = Object.values(getAdjectives());
     const adjective = adjectives[Math.floor(Math.random() * adjectives.length)];
-    parts.push(adjective);
+    parts.adjective = adjective;
   }
 
   if (useColor) {
     const colors = Object.values(getColors());
     const color = colors[Math.floor(Math.random() * colors.length)];
-    parts.push(color);
+    parts.color = color;
   }
 
   if (useNoun) {
     const nouns = Object.values(getNouns());
     const noun = nouns[Math.floor(Math.random() * nouns.length)];
-    parts.push(noun);
+    parts.noun = noun;
   }
 
   for (let i = 0; i < numberSets; i++) {
     const number = getRandomNumber(numberMin, numberMax);
     const formattedNumber = formatNumber(number);
-    parts.push(formattedNumber);
+    parts[`number${i + 1}`] = formattedNumber;
   }
 
   if (settings.randomOrder) {
-    parts.sort(() => Math.random() - 0.5);
+    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;
   }
 
-  return parts.join(`${settings.separator}`);
+
+  let semantics = settings.semantics && settings.semantics[lang] || settings.semantics.en;
+
+  const result = semantics.map((key) => {
+    if (key !== 'number') return parts[key];
+
+    return Object.values(parts).filter((part) => !isNaN(part)).join('-');
+  });
+  return result.join(`${settings.separator}`);
 }
 
-module.exports = generateId;
+module.exports = generateId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "human-ids",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "A library to generate human readable IDs",
   "main": "index.js",
   "scripts": {

package/tests/index.test.js

@@ -1,15 +1,64 @@
 const generateId = require('../index');
 
 describe('generateId', () => {
-  test('should return a unique ID', () => {
+  test('should return a unique ID with all possible scenarios', () => {
+    const allScenarios = [
+      {
+        lang: 'es',
+        adjective: true,
+        color: true,
+        noun: true,
+        randomOrder: false,
+        separator: '-',
+        asObject: false,
+        number: {
+          min: 0,
+          max: 9999,
+          sets: 1,
+          completeWithZeros: true
+        }
+      },
+      {
+        lang: 'en',
+        adjective: false,
+        color: true,
+        noun: true,
+        randomOrder: true,
+        separator: '_',
+        asObject: true,
+        number: {
+          min: 1000,
+          max: 9999,
+          sets: 2,
+          completeWithZeros: false
+        }
+      },
+      // Add more scenarios here...
+    ];
+
+    const ids = new Set();
+
+    for (const scenario of allScenarios) {
+      const id = generateId(scenario);
+
+      console.log(`Scenario: ${JSON.stringify(scenario, null, 2)}\nID: ${id}`);
+      ids.add(id);
+    }
+
+    // Assert uniqueness for all scenarios
+    expect(ids.size).toBe(allScenarios.length);
+  });
+
+  test('should return a unique ID with iterations', () => {
     const testLength = 1000;
     const settings = {
-      lang: 'en',
+      lang: 'es',
       adjective: true,
       color: true,
       noun: true,
       randomOrder: true,
       separator: '-',
+      asObject: false,
       number: {
         min: 0,
         max: 9999,
@@ -30,4 +79,4 @@ describe('generateId', () => {
     // Assert uniqueness
     expect(ids.size).toBe(testLength);
   });
-});
+});