deno-snowflake

❄ Deno module to work with Twitter’s Snowflake technology

Explication

Snowflake is, according to the official and archived repository, is a service for generating unique ID numbers at high scale.

Original Twitter’s Snowflake format

Snowflake repository.

Here is a representation of the default format I took from bwmarrin’s repository

+--------------------------------------------------------------------------+
| 1 Bit Unused | 41 Bit Timestamp |  10 Bit NodeID  |   12 Bit Sequence ID |
+--------------------------------------------------------------------------+

A Snowflake ID following the default settings:

• The ID is a 63 bit integer stored in an int 64.
• The first 41 bits are used to store the timestamp (in milliseconds), using a custom epoch (This provide 69 years of lifetime).
• The next 10 bits contains a Node ID (a range from 0 to 1023, so 2^10 nodes).
• The last 12 bits corresponds to a sequence number, which rolls over every 4096. This sequence is generally used as the increment number, a number incremented for every generated ID on the node.

The default settings allow the generation of 4096 unique IDs every millisecond, per Node ID.

Custom epoch

The Snowflake’s epoch can me modified by the entity using the Snowflake technology, which means you can use your own.

Here a list of some Snowflake’s epoch:

• Twitter Epoch (used by default by the module): 1288834974657 -> Nov 04 2010 01:42:54
• Discord Epoch: 1420070400000 -> Jan 01 2015 00:00:00

Alternative

sony/sonyflake is an alternative of Twitter’s Snowflakes which provide more lifetime (174 years instead of 69), can work on more nodes (up to 2^16 nodes instead of 2^10) but can generate less ID numbers per millisecond than Snowflakes (102.4 instead of 2^12 per node).

Getting Started

Requirements

You need deno to use this deno module.

Usage

Import the module to use it.

import * as Snowflake from 'https://x.nest.land/deno_snowflake@1.0.1/snowflake.ts';
// import * as Snowflake from "https://deno.land/x/deno_snowflake/snowflake@v1.0.1.ts";

Documentation

melt

export function melt(snowflakeID: string, epoch: number): MeltedSnowflake;

This function deconstructs a Snowflake ID and returns its information, such as the timestamp.

If no epoch provided, the module use the exported constant TWITTER_EPOCH.

generate

export function generate(options: SnowflakeIDGeneratorOptions): string;

This function generate a new Snowflake ID using given options and returns it.

If no options provided, the module use the following properties:

{
  timestamp: Date.now(),
  epoch: TWITTER_EPOCH,
  processID: 0,
  workerID: 1,
}

TWITTER_EPOCH

export const TWITTER_EPOCH = 1288834974657;

The Epoch Twitter uses for Snowflakes generation. This value is used by default in the melt function.

sequence

export let sequence = 0;

The sequence used in the generate function. The variable should not be modified and its exported only for reading the value.

MeltedSnowflake

export interface MeltedSnowflake {
    timestamp: number;
    processID: number;
    workerID: number;
    sequence: number;
    epoch: number;
    binary: string;
    stringID: string;
    bigIntID: bigint;
    date: Date;
}

Type of the object returned by the melt function.

• timestamp: Timestamp the Snowflake was created.
• processID: The ID of the process that generate the Snowflake ID.
• workerID: The ID of the worker that generate the Snowflake ID.
• sequence: Sequence in the Snowflake.
• epoch: The used Epoch in the Snowflake.
• binary: Binary representation of the Snowflake ID.
• stringID: The Snowflake ID as a string.
• bigIntID: The Snowflake ID as a BigInt.
• date: The Date the Snowflake was created.

License

The module is licensed under the MIT License. Please read LICENSE for more information.

Contributing

Thanks for wanting to contribute to deno_snowflake! Please read CONTRIBUTING.md and CODE_OF_CONDUCT.