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

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