Introducing SnowUUID: A Distributed UUID Generator Inspired by Snowflake

In distributed systems, ensuring unique IDs across multiple servers or processes can be challenging. IDs must be unique, quickly generated, and sometimes convey information about their source. Inspired by Twitter’s Snowflake ID generation algorithm, I developed SnowUUID, a distributed UUID generator designed for Node.js applications. SnowUUID combines precision and scalability to generate unique, time-ordered identifiers that can be customized for any distributed setup.

Why SnowUUID?

SnowUUID brings the power of Twitter’s Snowflake algorithm into a compact, easy-to-use npm package for JavaScript developers. Each ID generated by SnowUUID is a 64-bit integer, containing information about the timestamp, datacenter, worker, and sequence, making it ideal for distributed applications where each server or process generates IDs independently.

Features of SnowUUID

• Time-Ordered IDs: IDs are generated in a time-ordered sequence, ensuring that they can be sorted chronologically.
• Customization Options: SnowUUID allows configuration of the datacenter and worker IDs, supporting different setups across distributed systems.
• High Throughput: With a sequence limit per millisecond, SnowUUID can handle high-throughput requirements, preventing ID conflicts.

How SnowUUID Works

SnowUUID IDs are composed of multiple segments:

1. Timestamp: Ensures chronological ordering of IDs.
2. Datacenter ID: Distinguishes between different datacenters.
3. Worker ID: Distinguishes between different workers within a datacenter.
4. Sequence: Ensures multiple unique IDs can be created in the same millisecond.

Here’s a breakdown of the bit distribution for each segment:

Usage

Install SnowUUID from npm:

npm install snowuuid

To generate unique IDs with SnowUUID, import the package and initialize a new instance:

const { SnowUUID } = require('snowuuid');

// Initialize SnowUUID with options
const generator = new SnowUUID({
    epoch: 1609459200000n,  // Starting from January 1, 2021
    workerId: 1n,           // Unique ID for each worker
    datacenterId: 1n        // Unique ID for each datacenter
});

// Generate a unique ID
const uniqueId = generator.nextId();
console.log(uniqueId.toString());

Customizing SnowUUID

SnowUUID’s WorkerOptions interface provides customizable settings to adapt to your system:

• epoch: Custom starting time in milliseconds.
• workerId: Unique identifier for each worker within a datacenter.
• datacenterId: Unique identifier for each datacenter.

const generator = new SnowUUID({
    epoch: 1610000000000n,  // Custom epoch
    workerId: 3n,           // Worker ID
    datacenterId: 2n        // Datacenter ID
});

Under the Hood: The Code

At the core of SnowUUID is the nextId() function, which generates unique IDs by combining timestamp, datacenter ID, worker ID, and sequence bits. Here’s how it works:

• Clock Handling: The algorithm ensures the system clock is always moving forward. If the clock goes backward, an error is thrown to prevent duplicate IDs.
• Sequence Overflow Handling: When the sequence limit is reached within a millisecond, SnowUUID waits until the next millisecond to continue generating IDs.

Example Code: The nextId Function

nextId() {
    let timestamp = SnowUUID.now();

    if (timestamp < this.#lastTimestamp) {
        throw new Error(
            `Clock moved backwards. Unable to generate ID for ${this.#lastTimestamp - timestamp} milliseconds.`
        );
    }

    if (timestamp === this.#lastTimestamp) {
        this.#sequence = (this.#sequence + 1n) & SEQUENCE_MASK;
        if (this.#sequence === 0n) {
            timestamp = this.tilNextMillis(this.#lastTimestamp);
        }
    } else {
        this.#sequence = 0n;
    }

    this.#lastTimestamp = timestamp;

    return (
        ((timestamp - this.#epoch) << DEFAULT_TIMESTAMP_LEFT_SHIFT) |
        (this.#datacenterId << DEFAULT_DATACENTER_ID_SHIFT) |
        (this.#workerId << DEFAULT_WORKER_ID_SHIFT) |
        this.#sequence
    );
}

Conclusion

SnowUUID offers a powerful, customizable, and efficient solution for distributed UUID generation, perfect for applications that require high scalability and unique IDs across multiple systems. Whether for analytics, messaging, or microservices, SnowUUID ensures unique, time-ordered identifiers, helping you scale with confidence.

Explore SnowUUID on GitHub: SnowUUID Repository