hybrid-id-generator

Hybrid ID Generator

The Hybrid ID Generator is a powerful TypeScript-based library designed to produce unique identifiers by seamlessly combining timestamps, machine identifiers, sequence numbers, and random bits. This innovative approach ensures that each generated ID is unique and highly resilient against collisions, making it ideal for distributed systems.

This package is optimized for versatility and can be effortlessly utilized in both client-side and server-side environments, offering flexibility for a wide range of applications—from web development to microservices architecture.

Whether you are building a high-performance application that requires unique identifiers for database entries or need to track events in real-time, the Hybrid ID Generator provides a reliable solution that meets your needs.

Features

• Unique ID Generation: Generates unique IDs based on a combination of timestamp, machine ID, random bits, and sequence number, ensuring uniqueness across different instances.
• Base62 Encoding/Decoding: Supports encoding and decoding of IDs to and from Base62 format, facilitating easier storage and transmission.
• Event Emission: Emits events upon ID generation, allowing seamless integration with other application components and real-time tracking of ID creation.
• ID Expiration Check: Provides functionality to check if an ID has expired based on a specified duration, ensuring IDs are valid only for a predetermined time.
• Timestamp Obfuscation: Offers timestamp obfuscation to enhance security and prevent reverse engineering of ID generation.
• ID Validation: Includes methods to validate the format and structure of generated IDs.
• Configuration Options: Allows customization of parameters such as machine identifiers, sequence numbers, and random bit lengths for flexible use cases.
• Cross-Platform Support: Designed to work seamlessly in both client-side and server-side environments, making it versatile for various applications.

Installation

You can install the package via npm:

npm install hybrid-id-generator

Usage

Importing the Package You can use the package in both CommonJS and ES Module formats:

import { HybridIDGenerator } from 'hybrid-id-generator';

const idGenerator = new HybridIDGenerator({
    machineId: 1, // Unique identifier for the machine
    randomBits: 10, // Number of random bits
});

// Generate a single ID
const uniqueId = idGenerator.nextId();
console.log(`Generated ID: ${uniqueId}`);

// Check if an ID is valid
const isValid = idGenerator.isHybridID(uniqueId);
console.log(`Is valid ID: ${isValid}`);

// Decode an ID
const decodedId = idGenerator.decode(uniqueId);
console.log(`Decoded ID:`, decodedId);

Example

Here’s a quick example of how to use the HybridIDGenerator:

Server-Side Example

import { HybridIDGenerator } from 'hybrid-id-generator';

// Initialize the ID generator with a machine identifier and configuration options.
const idGenerator = new HybridIDGenerator({
  sequenceBits: 12,
  randomBits: 10,
});

// Generate a new unique ID.
const id: number = idGenerator.nextId();
console.log(`Generated ID: ${id}`);

Client-Side Example

import HybridIDGenerator from 'hybrid-id-generator'; // Adjust the path as necessary

// Initialize the ID generator with configuration options.
const idGenerator = new HybridIDGenerator({
  sequenceBits: 12,
  randomBits: 10,
  useCrypto: true, // Assuming this option is supported in your implementation
});

// Generate a new unique ID.
const newId: number = idGenerator.nextId();
console.log(`Generated ID: ${newId.toString()}`);

API

HybridIDGenerator API Documentation

Interfaces

HybridIDGeneratorOptions

Options for configuring the HybridIDGenerator.

Property	Type	Default	Description
sequenceBits	number	12	The number of bits for the sequence component.
randomBits	number	10	The number of bits for the random component.
entropyBits	number	5	The number of bits for the entropy component.
useCrypto	boolean	false	Whether to use cryptographic functions for random generation.
maskTimestamp	boolean	false	Whether to mask the timestamp during ID generation.
enableEventEmission	boolean	false	Whether to enable event emission for ID generation.
machineIdBits	number	12	The number of bits for the machine ID component.
machineIdStrategy	`'env'	'network'	'random'`
machineId	`number	string`	-

HybridIDInfo

Information about the generated Hybrid ID.

Property	Type	Description
timestamp	bigint	The timestamp portion of the Hybrid ID.
machineId	number	The machine ID portion of the Hybrid ID.
randomBits	number	The random bits portion of the Hybrid ID.
sequence	number	The sequence number of the Hybrid ID.
masked	boolean	Indicates whether the timestamp is masked.

Class: HybridIDGenerator

Constructor

constructor(options: HybridIDGeneratorOptions = {})

Initializes a new instance of HybridIDGenerator with the specified options.

Properties

• options: HybridIDGeneratorOptions & { sequence: number; lastTimestamp: bigint; maxSequence: number; maxMachineId: number; }
  • Gets the current options and state of the Hybrid ID generator.

Events

idGenerated

• Emitted whenever a new ID is generated. You can listen for this event as follows:

idGenerator.on('idGenerated', (id) => {
    console.log(`New ID generated: ${id}`);
});
idGenerator.nextId();

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue for any bugs or feature requests.