@street-devs/nest-snowflake-id - User Guide

Overview

The @street-devs/nest-snowflake-id package provides a highly customizable Snowflake ID generator for NestJS applications. This generator produces unique 64-bit IDs based on the Snowflake algorithm, which consists of a timestamp, a node (instance) ID, and a sequence number. It also includes decoding capabilities to extract the components of generated IDs.

Key Features:

• Customizable epoch: You can specify a custom start epoch for the ID generation.
• Worker and Data Center IDs: Each instance of the generator can have its own node ID, ensuring that generated IDs are unique across across multiple machines and data centers.
• Concurrency-safe: Handles sequence numbers within the same millisecond to avoid collisions.

---

Installation

To install the package in your NestJS project, run:

npm install --save @street-devs/nest-snowflake-id

---

Usage

1. Importing and Configuring the Module

To use @street-devs/nest-snowflake-id in your NestJS application, you need to import the module and configure it.

Example: Basic Usage

import { Module } from '@nestjs/common';
import { SnowflakeIdModule } from '@street-devs/nest-snowflake-id';

@Module({
  imports: [SnowflakeIdModule.forRoot()],
})
export class AppModule {}

Example: Custom Configuration

You can provide custom options:

import { Module } from '@nestjs/common';
import { SnowflakeIdModule } from '@street-devs/nest-snowflake-id';

import { Module } from '@nestjs/common';
import { SnowflakeIdModule } from 'nest-snowflake-id';

@Module({
  imports: [SnowflakeIdModule.forRoot({
    customEpoch: 1609459200000, // Custom epoch (Jan 1, 2021)
    dataCenterId: 1, // Data Center ID
    workerId: 1, // Worker ID
  })],
})
export class AppModule {}

• customEpoch is an optional UNIX timestamp that marks the start of your Snowflake IDs. If not provided, the current time is used.
• dataCenterId allows you to set a unique data center ID, which should be between 0 and 31 (based on 5-bit configuration).
• workerId: allows you to set a unique worker ID, which should be between 0 and 31 (based on 5-bit configuration).

2. Generating IDs

You can generate Snowflake IDs by injecting the SnowflakeIdService into your service or controller.

Example: ID Generation

import { Injectable } from '@nestjs/common';
import { SnowflakeIdService } from '@street-devs/nest-snowflake-id';

@Injectable()
export class MyService {
  constructor(private readonly snowflakeIdService: SnowflakeIdService) {}

  generateId() {
    const id = this.snowflakeIdService.generate();
    console.log(`Generated Snowflake ID: ${id}`);
    return id;
  }
}

The generate() method will return a unique 64-bit Snowflake ID as a bigint.

3. Decoding IDs

You can also decode a Snowflake ID to extract its timestamp, instance ID, and sequence number.

Example: ID Decoding

import { Injectable } from '@nestjs/common';
import { SnowflakeIdService } from '@street-devs/nest-snowflake-id';

@Injectable()
export class MyService {
  constructor(private readonly snowflakeIdService: SnowflakeIdService) {}

  decodeId(id: bigint) {
    const decoded = this.snowflakeIdService.decode(id);
    console.log(`Decoded Snowflake ID:`, decoded);
    return decoded;
  }
}

The decode() method will return an object containing:

• dateTime: The exact date and time when the ID was generated.
• timestamp: Raw timestamp value.
• dataCenterId: The ID of the data center.
• workerId: The ID of the worker node.
• sequence: The sequence number ensuring uniqueness within the same millisecond.
• epoch: The custom epoch used.

4. Global Module Usage

If you want to make the SnowflakeIdService globally available throughout your application, set the global option to true:

@Module({
  imports: [SnowflakeIdModule.forRoot({ global: true })],
})
export class AppModule {}

---

API Reference

SnowflakeIdService Methods

1. generate(): Generates a unique 64-bit Snowflake ID.

   • Returns: bigint

2. decode(id: bigint): Decodes the given Snowflake ID.

   • Parameters:
     • id: The Snowflake ID to decode.
   • Returns: { dateTime: Date, timestamp: bigint, dataCenterId: bigint, workerId: bigint, sequence: bigint, epoch: number }

---

Technical Details

ID Structure (64 bits):

• Epoch (42 bits): Used to store the timestamp (up to 139 years).
• Worker ID (5 bits): Identifies the node generating the ID (supports up to 32 workers).
• Data Center ID (5 bits): Identifies the data center (supports up to 32 data centers).
• Sequence (12 bits): Ensures uniqueness within the same millisecond (can generate up to 4096 IDs per millisecond).

Edge Cases:

• When multiple IDs are generated within the same millisecond, the sequence number will increment. If the sequence number reaches the limit (1023), the generator waits for the next millisecond.

---

Example Use Case

const snowflake = new SnowflakeId({ 
  customEpoch: 1609459200000, 
  dataCenterId: 1, 
  workerId: 1 
});
const newId = snowflake.generate();
console.log(newId);  // Example output: 93977444276639021
const decoded = snowflake.decode(newId);
console.log(decoded); 
// {
//   "dateTime": "2024-09-16T07:52:48.732Z",
//   "timestamp": 1726473168732,
//   "dataCenterId": 1,
//   "workerId": 1,
//   "sequence": 1325,
//   "epoch": 1704067200000
// }

---

License

This package is open-sourced under the MIT License.