Snoww

Snoww is a lightweight TypeScript library for generating unique 64-bit IDs at high scale with some simple guarantees.

Snoww is based on Discord's implementation of Twitter's Snowflake ID format.

Binary Representation

111111111111111111111111111111111111111111 11111 11111 111111111111
64                                         22    17    12          0

Format Structure

| Field | Bits | Number of bits | Description | |------------|----------|----------------|---------------------------------------| | Timestamp | 63 to 22 | 42 bits | Milliseconds since the Epoch | | Worker ID | 21 to 17 | 5 bits | Worker ID | | Process ID | 16 to 12 | 5 bits | Process ID | | Increment | 11 to 0 | 12 bits | Increment within the same millisecond |

Installation

npm install snoww

Usage

import { SnowflakeFactory } from "snoww";

// Create a snowflake generator
const snowflake = new SnowflakeFactory({
    epoch: new Date("2020-01-01"),  // Required: epoch timestamp
    workerId: 1,                    // Optional: defaults to 0
    processId: 0                    // Optional: defaults to 0
});

// Generate IDs
const id = snowflake.generate(); // Returns bigint
const idString = id.toString();  // Convert to string

// Deconstruct ID
const parts = snowflake.deconstruct(id);
// { id, epoch, timestamp, workerId, processId, increment }

// Extract timestamp
const timestamp = snowflake.timestamp(id);
const date = new Date(timestamp);

// Create ID from timestamp
const boundaryId = snowflake.fromTimestamp(new Date("2024-01-01"), 0);

// Compare IDs
SnowflakeFactory.compare(id1, id2); // Returns: -1, 0, or 1

// Sort array of IDs
ids.sort((a, b) => SnowflakeFactory.compare(a, b));

License

MIT