simple-snowflake-id v1.0.2

simple-snowflake-id

A lightweight TypeScript implementation of Twitter's Snowflake ID generator for distributed systems.

Features

• 🚀 High Performance: Generate 1M IDs/second on modern hardware
• ⚙️ Configurable: Custom epochs, datacenter/machine IDs (0-31)
• 🔍 Debuggable: Built-in ID decomposition
• 📦 Zero Dependencies: Pure TypeScript implementation
• 🔧 Type Safe: Full TypeScript support

Usage

Installation

npm install simple-snowflake-id

Basic Usage

import { Snowflake } from 'simple-snowflake-id';

// Initialize with default configuration
const generator = new Snowflake();

// Generate ID as BigInt
const id = generator.generate();
console.log('Generated ID:', id); // 182305294335246336n

// Generate as String
const strId = generator.generate('string');
console.log('String ID:', strId); // "182305294335246336"

ID Decomposition

const details = Snowflake.decompose(id);
console.log('Decomposed ID:', details);
/* Output:
{
  timestamp: 1712345678901n,
  datacenterId: 0,
  machineId: 0,
  sequence: 0,
  epoch: 1288834974657n
}
*/

Advanced Configuration

// Custom epoch (January 1, 2024 UTC)
const CUSTOM_EPOCH = 1704067200000n;

const customGenerator = new Snowflake({
  epoch: CUSTOM_EPOCH,
  datacenterId: 5,  // 0-31
  machineId: 10     // 0-31
});

// Bulk generation
const ids = Array(1000).fill(null).map(() => customGenerator.generate());

API Reference

Snowflake Class

Constructor

new Snowflake(config?: SnowflakeConfig)

Methods

• generate(format?: 'bigint' | 'string')
• static decompose(id: bigint | string, epoch?: bigint)

Performance

Development

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Run benchmarks
npm run benchmark

License

MIT © Yaroslav Kharchenko

Support:

• GitHub: yarik01337/simple-snowflake-id
• Email: kharchnekoyaroslav@gmail.com