Hybrid ID Generator

Comparison: UUIDv4 vs UUIDv7 vs Hybrid ID

Criterion	UUIDv4	UUIDv7 (RFC 9562)	Hybrid ID (this library)
Chronological order	No	Yes	Yes (wall-clock, configurable)
Size	128 bits	128 bits	87 bits (smaller)
Standard / ecosystem	Yes	Yes	No (custom format)
Explicit shard ID	No	No	Yes (machine/shard field)
Expiry check	No	No	Yes (if not masked)
Decode / info	No	No	Yes (timestamp, machineId, etc.)
Index-friendly	No	Yes	Yes (numeric, time-ordered)

When to use which: Use UUIDv7 when you want a standard, time-sortable ID with broad tooling support. Use Hybrid ID when you need smaller size (87 vs 128 bits), an explicit machine/shard ID for routing, or built-in decode/expiry/masking.

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 in both Node.js and browser environments where crypto.getRandomValues is available.

Environment support

Node.js: Full support (all options, including maskTimestamp, machineIdStrategy: 'env' and 'network').
Browser: ID generation works when crypto.getRandomValues is available. maskTimestamp (timestamp obfuscation) and machineIdStrategy: 'env' | 'network' require Node.js (they use the crypto and os modules).
Timestamp: By default uses wall-clock time (Date.now(), ms since Unix epoch) for chronological ordering and expiry; set useWallClock: false to use monotonic time (Node-only).
Expiry: isIdExpired(id, duration) returns false when maskTimestamp is true, because the timestamp cannot be read from the ID.

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