A powerful hybrid ID generator that combines timestamps, machine IDs, random bits, and sequence numbers to create globally unique identifiers. Features collision prevention, Base62 encoding, and optional ID expiry tracking, ideal for distributed systems a
npm install hybrid-id-generator| 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.
crypto.getRandomValues is available.maskTimestamp, machineIdStrategy: 'env' and 'network').crypto.getRandomValues is available. maskTimestamp (timestamp obfuscation) and machineIdStrategy: 'env' | 'network' require Node.js (they use the crypto and os modules).Date.now(), ms since Unix epoch) for chronological ordering and expiry; set useWallClock: false to use monotonic time (Node-only).isIdExpired(id, duration) returns false when maskTimestamp is true, because the timestamp cannot be read from the ID.You can install the package via npm:
``bash`
npm install hybrid-id-generator
ts
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);
`
$3
Here’s a quick example of how to use the HybridIDGenerator:Server-Side Example
`js
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
`js
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
$3
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' | Strategy used for generating the machine ID. |
| machineId | number | string | - | The initial machine ID to use (must be validated). |
| timestampBits | number | 42 | The number of bits for the timestamp (ms since Unix epoch, ~139 years). |
| useWallClock | boolean | true | Use wall-clock time (Date.now()) for chronological order and expiry; false = monotonic (Node-only). |$3
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
$3
`typescript
constructor(options: HybridIDGeneratorOptions = {})
`
Initializes a new instance of HybridIDGenerator with the specified options.
$3
- options: HybridIDGeneratorOptions & { sequence: number; lastTimestamp: bigint; maxSequence: number; maxMachineId: number; timestampBits: number; useWallClock: boolean; maxTimestamp: bigint; }
- 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:
`js
idGenerator.on('idGenerated', (id) => {
console.log(New ID generated: ${id});
});
idGenerator.nextId();
`Releasing
Release is prepared locally; publishing to npm is done by GitHub Actions when you push a version tag.
1. Prepare (bump version, update CHANGELOG, create tag; no publish):
`bash
npm run prepare-release
`
2. Push the branch and the tag (the tag is required for the action to publish):
`bash
git push --follow-tags
`
If you only run git push, the new tag (e.g. v3.1.0) is not pushed and the workflow will not publish. Use --follow-tags or git push origin v3.1.0`.