@Persian-Caesar/Snowflake-ID

A modern, flexible, and high-performance Snowflake ID generator for TypeScript and JavaScript.

Inspired by Twitter Snowflake and Discord's ID system, this library gives you full control over ID length, format, and structure while maintaining near-zero collision guarantees.

---

🌐 Documentation

• English → README.md This file.
• فارسی → README.fa.md

---

✨ Features

• Highly Customizable — Control time bits, worker bits, sequence bits
• Multiple Output Formats — Decimal, Base62 (recommended), Base36, or custom alphabet
• Short IDs Support — Generate 8–13 character IDs (Discord-like, Telegram-like, etc.)
• Built-in Parsing — Extract timestamp, worker ID, and sequence from any ID
• Batch Generation — Efficiently generate thousands of IDs
• TypeScript First — Full type safety with excellent JSDoc
• Collision Safe — Proper sequence handling and time drift protection
• Zero Dependencies — Lightweight and fast

---

📦 Installation

npm install @persian-caesar/snowflake-id
# or
yarn add @persian-caesar/snowflake-id
# or
pnpm add @persian-caesar/snowflake-id

---

🚀 Quick Start

import Snowflake from '@persian-caesar/snowflake-id';

const snowflake = new Snowflake();

console.log(snowflake.generate());
// 1749123456789012345

Discord-style Short IDs (Recommended)

const discordStyle = new Snowflake({
  timeBits: 38,
  workerBits: 8,
  seqBits: 10,
  base62: true
});

console.log(discordStyle.generate());
// Example: 9K8mL2pXvR7t

---

⚙️ Configuration Options

Option	Type	Default	Description
timeBits	number	42	Bits for timestamp (higher = longer lifespan)
workerBits	number	10	Bits for worker/node ID
seqBits	number	12	Bits for sequence per millisecond
epoch	number	0	Custom epoch (ms) - highly recommended
workerId	number	1	Unique ID for this instance
base62	boolean	false	Use Base62 encoding (short & URL-safe)
base36	boolean	false	Use Base36 encoding
customAlphabet	string	...	Custom character set for encoding

Total bits must not exceed 64.

---

📖 Examples

1. Twitter-like (Long & Precise)

const twitter = new Snowflake({
  epoch: 1288834974657, // Twitter epoch (November 4, 2010)
  timeBits: 41,
  workerBits: 5,
  seqBits: 18,
});

console.log(twitter.generate());
// 1749123456789012345

2. Discord-like (Short & Clean)

const discord = new Snowflake({
  timeBits: 38,
  workerBits: 8,
  seqBits: 10,
  base62: true
});

console.log(discord.generateBatch(5));
// ['9K8mL2pXvR7t', '9K8mL2pXvR7u', '9K8mL2pXvR7v', ...]

3. Very Short IDs (8-10 characters)

const short = new Snowflake({
  timeBits: 32,
  workerBits: 6,
  seqBits: 8,
  base62: true
});

console.log(short.generate());
// Example: 7X9kP2mQ

4. Using Custom Alphabet

const branded = new Snowflake({
  base62: true,
  customAlphabet: "ABCDEFGHJKLMNPQRSTUVWXYZ23456789" // No confusing characters
});

---

🔍 Parsing IDs

const id = discord.generate();

const parsed = discord.parse(id);

console.log(parsed);
/*
{
  timestamp: 2025-05-30T12:34:56.789Z,
  timestampMs: 1749123456789,
  workerId: 7,
  sequence: 42,
  id: "9K8mL2pXvR7t"
}
*/

console.log(discord.timeFromId(id)); // Date object

---

🛠 API Reference

Constructor

new Snowflake(options?: SnowflakeOptions)

Main Methods

• .generate() → string
• .generateBatch(count: number) → string[]
• .parse(id: string | bigint) → ParsedSnowflake
• .timeFromId(id: string | bigint) → Date
• .isValid(id: string) → boolean

---

⚡ Performance

This library is optimized for high throughput:

• Single ID generation: ~0.02ms
• Batch of 1000 IDs: ~8-12ms

Tip: Reuse the same Snowflake instance instead of creating new ones repeatedly.

---

🔒 Collision Safety

• Uses proper sequence rollover with time waiting
• Supports multiple workers safely
• Custom epoch prevents ID overlap across projects
• 64-bit structure with configurable distribution

---

📊 Bit Allocation Examples

Use Case	timeBits	workerBits	seqBits	Approx. Length (Base62)	Lifespan
Twitter Style	41	5	18	18-19 chars	~69 years
Discord Style	38	8	10	12-13 chars	~8.5 years
Short IDs	32	6	8	9-10 chars	~136 years
Ultra Short	30	5	8	8-9 chars	~34 years

---

🧪 Testing & Validation

const sf = new Snowflake({ base62: true });

const id = sf.generate();
console.log(sf.isValid(id)); // true

---

📄 License

MIT License - feel free to use in commercial and open-source projects.

---

🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the project
2. Create your feature branch
3. Commit your changes
4. Push and open a Pull Request

---

Made with ❤️ for scalable systems.

---

Have questions? Feel free to open an issue or discuss use cases.