npm package: @street-devs/snowflake-id
Description: Provides a highly customizable Snowflake ID generator for Javascript/Typescript 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 i
Author: duysolo
Latest version: 1.0.10


# `@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.