@street-devs/snowflake-id User Guide

Overview

The @street-devs/snowflake-id package provides a class for generating unique 64-bit IDs using the Snowflake algorithm. It supports customizable options for epoch, machine ID, and worker ID, making each ID unique across distributed systems. Each generated ID consists of a timestamp, data center ID, worker ID, and sequence number.

Installation

Install the package via npm:

npm install @street-devs/snowflake-id

Usage

1. Import and Configure

import { SnowflakeId, SnowflakeIdOptions } from '@street-devs/snowflake-id';

2. Initialize SnowflakeId

The SnowflakeId class accepts an optional SnowflakeIdOptions configuration object to specify epoch, machine ID, and worker ID.

const options: SnowflakeIdOptions = {
  customEpoch: Date.now(),  // Optional, defaults to 2024-01-01T00:00:00Z
  machineId: 1,             // Optional, unique identifier for the machine
  workerId: 2               // Optional, unique identifier for the worker
};
const snowflakeId = new SnowflakeId(options);

3. Generate an ID

Use the generate() method to create a unique Snowflake ID.

const id = snowflakeId.generate();
console.log(id.toString());  // Example output: '1234567890123456789'

4. Decode an ID

The decode(id) method extracts the components of a Snowflake ID, providing details on when and where the ID was generated.

const decoded = snowflakeId.decode(id);
console.log(decoded);
// Output:
// {
//   dateTime: Date object,
//   timestamp: bigint,
//   dataCenterId: bigint,
//   workerId: bigint,
//   sequence: bigint,
//   epoch: number
// }

API Reference

SnowflakeId Class

Constructor: new SnowflakeId(options?: SnowflakeIdOptions)

• options.customEpoch - Custom epoch time in milliseconds (default: 2024-01-01T00:00:00Z).-
• options.machineId - Machine ID for uniqueness across machines (default: random).-
• options.workerId - Worker ID for uniqueness across workers (default: random).

Methods

• generate(): bigint - Generates a unique Snowflake ID as a 64-bit bigint.
• decode(id: bigint): SnowflakeIdDecoded - Decodes a given Snowflake ID, returning:
• dateTime: Date instance based on the timestamp.
• timestamp: Timestamp component of the ID.
• dataCenterId: Data center ID.
• workerId: Worker ID.
• sequence: Sequence number to prevent collisions within the same millisecond.
• epoch: Custom epoch used for the timestamp.

Examples

const id = snowflakeId.generate();
console.log(`Generated ID: ${id}`);

const decodedId = snowflakeId.decode(id);
console.log(`Decoded components: `, decodedId);

Additional Notes

• JSON Serialization: Includes a custom BigInt.toJSON() method that converts BigInt values to numbers for JSON compatibility.
• Bit Structure: Uses a fixed 64-bit Snowflake ID structure, allocating 42 bits for the timestamp, 5 bits for data center ID, 5 bits for worker ID, and 12 bits for the sequence.