Unique ID Generator

A high-performance, timestamp-based 64-bit unique ID generator inspired by Twitter's Snowflake architecture. Suitable for distributed systems, supporting up to 4096 unique IDs per millisecond per machine.

✨ Features

• ✅ 64-bit globally unique ID generation
• 🕒 Based on timestamp, with millisecond precision
• ⚙️ Uses os module to generate unique machine ID
• ⚡️ 4096 IDs per millisecond per node
• 🧩 decodeId() support to reverse-engineer timestamp, machineId, sequence
• 📦 Lightweight, TypeScript-first implementation

---

📦 Installation

1npm install unique-id-generator-ts

NPM package: unique-id-generator-ts

🚀 Usage

1import { UniqueIdGenerator } from 'unique-id-generator-ts';
2
3const generator = new UniqueIdGenerator();
4
5const id = generator.generateUniqueId();
6console.log(id); // e.g., 1308924728312342528
7
8// Decode the ID
9const decoded = generator.decodeId(id);
10console.log("Decoded Info:", decoded);
11

🛠️ Constructor with Custom Epoch

You can optionally pass a custom epoch (in milliseconds) to control the base timestamp used in ID generation.

1import { UniqueIdGenerator } from 'unique-id-generator-ts';
2
3// Default epoch (if not passed): 1700000000000
4const generator = new UniqueIdGenerator(1700000000000);

📝 Note: The epoch affects the timestamp part of your ID. Use a consistent epoch across services to maintain global uniqueness and sortability.

📤 Output of decodeId(id)

1{
2  timestamp: 1728012388123,
3  machineId: 43,
4  sequence: 212
5}

🧠 ID Structure: 64-bit Snowflake-Inspired Format

Each ID is a 64-bit integer, structured as follows:

Bits	Field	Description
41	Timestamp	Milliseconds since custom epoch
10	Machine ID	Supports 1024 unique nodes
12	Sequence	Allows 4096 IDs per millisecond per node

⚠️ Important Note

• To ensure ID uniqueness and efficient performance, always create only one instance of UniqueIdGenerator per process.
• Creating multiple instances can lead to duplicated sequence numbers, especially within the same millisecond, and may result in non-unique IDs.

✅ Recommended:

1// Instantiate once at app startup
2const generator = new UniqueIdGenerator();
3
4// Use the same instance throughout your app
5const id = generator.generateUniqueId();

✅ Pros

• 📏 Compact: Fits in a 64-bit integer (unlike UUIDs)
• ⏱ Time-ordered: Great for databases or event logs
• ⚡️ Fast: Uses simple bitwise operations for performance

⚠️ Cons

• 🧩 Slightly more complex than concatenation
• 🔐 Requires machine ID coordination (to avoid collisions)
• 🔁 Sequence limit of 4096 per ms per machine