Semantic ID Generator - NPM Package

    GitHub NPM version Open Source Love

    Logo

    Table of Contents

    Introduction

    Semantic ID Generator is a Node.js package designed to generate structured and meaningful unique identifiers, named “Semantic ID”. These identifiers are composed of different “compartments” each having a specific “semantic meaning” and generation strategy.

    Latest Updates (v1.1.0):

    What is a Semantic Identifier?

    A Semantic ID is an identifier that implements following AMASE data architecture principles:

    A semantic id follows the pattern:

    {date concept name}{name separator}{compartment 1}{compartment separator}{compartment 2}{compartment separator}...{compartment N}

    Examples

    Here a few examples of generated semantic identifiers:

    String Generation Strategies

    Semantic ID Generator uses different string generation strategies to generate each compartment of the semantic ID. Here are the currently available strategies:

    These strategies can be assigned to each compartment in the Semantic ID Generator configuration. This allows you to customize the generation of each part of the semantic ID according to your requirements.

    Installation

    Prerequisites

    Before you can use the Semantic ID Generator, you must have certain software installed on your computer:

    After installing Node.js and NPM, you need to install the dependencies of the Semantic ID Generator:

    npm install uuid

    Then install the Semantic ID Generator library

    npm install semantic-id-generator

    ES Module Support

    This package is now a pure ES module. To use it in your project:

    For ES Module projects (recommended):

    import SemanticIDGenerator from 'semantic-id-generator';

    For CommonJS projects:

    const SemanticIDGenerator = await import('semantic-id-generator');
const generator = new SemanticIDGenerator.default();

    TypeScript Support

    The library includes full TypeScript support with comprehensive type definitions. If you’re using TypeScript, you’ll get:

    import SemanticIDGenerator, { 
  SemanticIDGeneratorConfig, 
  Compartment, 
  GenerationStrategy, 
  LanguageCode 
} from 'semantic-id-generator';

// Type-safe configuration
const config: SemanticIDGeneratorConfig = {
  dataConceptSeparator: '|',
  compartmentSeparator: '-',
  compartments: [
    { name: 'prefix', length: 8, generationStrategy: 'visible characters' },
    { name: 'base64_part', length: 24, generationStrategy: 'base64' },
    { name: 'suffix', length: 12, generationStrategy: 'hexadecimal' }
  ]
};

const generator = new SemanticIDGenerator(config);
const id = generator.generateSemanticID('document');

    Usage

    Basic Usage

    import SemanticIDGenerator from 'semantic-id-generator';
const generator = new SemanticIDGenerator();
const id = generator.generateSemanticID('person');
console.log(id); // Outputs looks like 'person|abcd-abcdefgh-abcdefghijkl'

    Advanced Usage

    import SemanticIDGenerator from 'semantic-id-generator';

const config = { 
    dataConceptSeparator: '|', 
    compartmentSeparator: '-', 
    compartments: [
        { name: 'part1', length: 10, generationStrategy: "visible characters"},
        { name: 'part2', length: 10, generationStrategy: "numbers"},
        { name: 'part3', length: 32, generationStrategy: "hexadecimal"}
    ] 
};

const generator = new SemanticIDGenerator(config);
const id = generator.generateSemanticID('person');
console.log(id);

    Example with Base64 strategy:

    import SemanticIDGenerator from 'semantic-id-generator';

const config = { 
    dataConceptSeparator: '|', 
    compartmentSeparator: '-', 
    compartments: [
        { name: 'prefix', length: 8, generationStrategy: "visible characters"},
        { name: 'base64_part', length: 24, generationStrategy: "base64"},
        { name: 'suffix', length: 12, generationStrategy: "hexadecimal"}
    ] 
};

const generator = new SemanticIDGenerator(config);
const id = generator.generateSemanticID('document');
console.log(id); // Example: 'document|Kj8mNx2-AbCdEfGhIjKlMnOpQrStUv-1a2b3c4d5e6f'

    Example with Passphrase strategy:

    import SemanticIDGenerator from 'semantic-id-generator';

const config = { 
    dataConceptSeparator: '|', 
    compartmentSeparator: '-', 
    compartments: [
        { name: 'prefix', length: 8, generationStrategy: "visible characters"},
        { name: 'passphrase_part', length: 25, generationStrategy: "passphrase"},
        { name: 'suffix', length: 12, generationStrategy: "hexadecimal"}
    ] 
};

const generator = new SemanticIDGenerator(config);
const id = generator.generateSemanticID('user_session');
console.log(id); // Example: 'user_session|Kj8mNx2-applebananacherrydragon-1a2b3c4d5e6f'

**Example with language configuration:**

```javascript
import SemanticIDGenerator from 'semantic-id-generator';

// Default behavior: uses all languages
const defaultConfig = { 
    dataConceptSeparator: '|', 
    compartmentSeparator: '-', 
    compartments: [
        { name: 'passphrase', length: 25, generationStrategy: "passphrase"}
    ] 
};

const defaultGenerator = new SemanticIDGenerator(defaultConfig);
const mixedId = defaultGenerator.generateSemanticID('session');
console.log(mixedId); // Example: 'session|applepommemanzanaapfel'

// Specific language configuration
const englishConfig = { 
    dataConceptSeparator: '|', 
    compartmentSeparator: '-', 
    languageCode: 'eng',
    compartments: [
        { name: 'passphrase', length: 25, generationStrategy: "passphrase"}
    ] 
};

const frenchConfig = { 
    dataConceptSeparator: '|', 
    compartmentSeparator: '-', 
    languageCode: 'fra',
    compartments: [
        { name: 'passphrase', length: 25, generationStrategy: "passphrase"}
    ] 
};

const englishGenerator = new SemanticIDGenerator(englishConfig);
const frenchGenerator = new SemanticIDGenerator(frenchConfig);

const englishId = englishGenerator.generateSemanticID('session'); // English only
const frenchId = frenchGenerator.generateSemanticID('session');   // French only

console.log(englishId); // Example: 'session|applebananacherrydragon'
console.log(frenchId);  // Example: 'session|pommebananejardinmaison'

    Supported Languages:

    Note: By default, the passphrase strategy uses words from all languages. To restrict to a specific language, add languageCode to the configuration.

    
### TypeScript Examples

For comprehensive TypeScript examples, see the `examples/typescript-example.ts` file. Here are some highlights:

**Type-safe configuration building:**
```typescript
import { ConfigurationBuilder } from 'semantic-id-generator';

const config = new ConfigurationBuilder()
  .setDataConceptSeparator('|')
  .setCompartmentSeparator('-')
  .addCompartment({ name: 'prefix', length: 6, generationStrategy: 'visible characters' })
  .addCompartment({ name: 'uuid', length: 32, generationStrategy: 'hexadecimal' })
  .setLanguageCode('eng')
  .build();

    Type validation utilities:

    import { validateStrategy, validateLanguageCode } from 'semantic-id-generator';

// Validate generation strategies
console.log(validateStrategy('base64')); // true
console.log(validateStrategy('invalid')); // false

// Validate language codes
console.log(validateLanguageCode('eng')); // true
console.log(validateLanguageCode('invalid')); // false

    Error handling with TypeScript:

    try {
  const generator = new SemanticIDGenerator();
  const id = generator.generateSemanticID('test');
} catch (error) {
  // TypeScript knows this is an Error
  console.error((error as Error).message);
}

    Default Values

    If you do not specify certain configuration options when creating a new Semantic ID Generator, the library uses the following default values:

    Performance

    The Semantic ID Generator is designed for high performance and security. Here are the performance benchmarks from our test suite:

    Performance Benchmarks

    General Performance:

    Unicode String Generation:

    String Generation Strategies Performance:

    Security Features

    All string generation uses cryptographically secure random number generation:

    Test Coverage

    The library includes comprehensive test coverage:

    Test Suites:

    Test Categories:

    Total Tests: 48+ passing tests covering all aspects of the library.

    Current Dependencies

    Production Dependencies:

    Development Dependencies:

    All dependencies are updated to their latest secure versions as of August 2025.

    Run unit tests

    Run from your command line interface (Bash, Ksh, Windows Terminal, etc.):

    npm test

    For TypeScript-specific tests:

    npm run test:typescript

    License

    This project is licensed under MIT License.

    About the Author

    Semantic ID Generator is created by Yannick Huchard - CTO. For more information, visit: